Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Standard practices for incomplete/semi-experimental methods #49296

Open
Tokazama opened this issue Apr 8, 2023 · 1 comment
Open

Standard practices for incomplete/semi-experimental methods #49296

Tokazama opened this issue Apr 8, 2023 · 1 comment

Comments

@Tokazama
Copy link
Contributor

Tokazama commented Apr 8, 2023

It's pretty hard to figure out what's going on in Julia Base for newbies given all the undocumented internals. There are a lot of comments but those are poorly maintained and have variable quality. I propose we require documentation with some standard !!! warning Unstable API for all methods that are used throughout Julia Base but are not intended for public use.

This is related to #48819, but it's probably safe to add a documentation requirement to the contributors guide prior to any other bells and whistles.
@Tokazama
Copy link
Contributor Author

#49298 is a good example where this has bit us in the ass. There appears to be two packages that use Base.unionlen although it is undocumented and not exported. Bike-shedding code is already obnoxious enough without worrying about people using stuff that is clearly not intended to be used outside of Base.

Tokazama added a commit to Tokazama/julia that referenced this issue Apr 10, 2023
@Tokazama
Guidelines for documenting usntable contributions (JuliaLang#49296)
a28565c 
Encourage documentation of contributions that may be unstable but
require explicit admonition.
Also add review of "Writing Documentation" to contributors checklist
ViralBShah pushed a commit that referenced this issue Apr 19, 2023
@Tokazama
Guidelines for documenting usntable contributions (#49296) (#49309)
b664693 
Encourage documentation of contributions that may be unstable but
require explicit admonition.
Also add review of "Writing Documentation" to contributors checklist
ViralBShah added a commit that referenced this issue Apr 19, 2023
@ViralBShah
Revert "Guidelines for documenting usntable contributions (#49296) (#…
ed64898 
…49309)"

This reverts commit b664693.
ViralBShah added a commit that referenced this issue Apr 19, 2023
@ViralBShah
Revert "Guidelines for documenting usntable contributions (#49296) (#…
174e138 
…49309)" (#49427)

This reverts commit b664693.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@Tokazama