Missing docstrings for public/exported symbols

[stevengj]

This is a tracking issue for public/exported symbols missing docstrings that were identified with the help of #52723. Please check them off as they get fixed and link the corresponding PRs (which should also enable a @test isempty(Docs.undocumented_names(ThisModule)) regression test).

Note that this is separate from the issue of whether those docstrings are included in the manual (#19529).

• [ ] Core: AtomicMemoryRef, ConcurrencyViolationError, Exception, GenericMemoryRef, GlobalRef, IO, LineNumberNode, Method, SegmentationFault, TypeVar, arrayref, arrayset, arraysize, const_arrayref

Base and public/exported submodules thereof:

• [ ] Base: BufferStream, CanonicalIndexError, CapturedException, Filesystem, IOServer, InvalidStateException, Order, PipeEndpoint, Sort, TTY
• [x] Base.Sys: CPU_NAME, JIT, cpu_info, cpu_summary (#52777)
• [ ] Base.Filesystem:
  • [ ] File, Filesystem, cptree, futime, rename, sendfile, unlink
  • [x] JL_O_APPEND, JL_O_ASYNC, JL_O_CLOEXEC, JL_O_CREAT, JL_O_DIRECT, JL_O_DIRECTORY, JL_O_DSYNC, JL_O_EXCL, JL_O_FSYNC, JL_O_LARGEFILE, JL_O_NDELAY, JL_O_NOATIME, JL_O_NOCTTY, JL_O_NOFOLLOW, JL_O_NONBLOCK, JL_O_PATH, JL_O_RANDOM, JL_O_RDONLY, JL_O_RDWR, JL_O_RSYNC, JL_O_SEQUENTIAL, JL_O_SHORT_LIVED, JL_O_SYNC, JL_O_TEMPORARY, JL_O_TMPFILE, JL_O_TRUNC, JL_O_WRONLY, S_IRGRP, S_IROTH, S_IRUSR, S_IRWXG, S_IRWXO, S_IRWXU, S_IWGRP, S_IWOTH, S_IWUSR, S_IXGRP, S_IXOTH, S_IXUSR (#53247)
• [ ] Base.Docs: @var
• [ ] Base.Broadcast: dotview
• [ ] Base.Order: DirectOrdering, ForwardOrdering, Order, ordtype
• [ ] Base.Sort: Algorithm, ~~SMALL_ALGORITHM~~ (#53807), SMALL_THRESHOLD, Sort

Standard Library:

• [x] Libdl: Libdl (#52825)
• [x] TOML: TOML (#52834)
• [x] Artifacts: Artifacts (#52913)
• [x] Dates: adjust (#52914)
• [x] Unicode: Unicode (#52761)
• [x] Markdown: @doc_str, @md_str, html, latex (#52733 and #52606)
• [ ] Serialization: AbstractSerializer, Serializer
• [ ] REPL: AbstractREPL, BasicREPL, LineEditREPL, StreamREPL (#52876)
• [x] Printf: Printf (#52791)
• [x] InteractiveUtils: InteractiveUtils (https://github.com/JuliaLang/julia/pull/53206)
• [ ] Profile: Allocs (#53559)
• [x] LinearAlgebra: ColumnNorm, LAPACKException, NoPivot, RankDeficientException, RowMaximum, RowNonZero, copy_transpose! (#52934)
• [x] Logging: AboveMaxLevel, BelowMinLevel
• [ ] FileWatching: FDWatcher, FileMonitor, FolderMonitor, PollingFileWatcher
• [x] SparseArrays: fkeep! (https://github.com/JuliaSparse/SparseArrays.jl/pull/503)
• [x] Tar: Tar (https://github.com/JuliaIO/Tar.jl/pull/173)
• [ ] Pkg: PKGMODE_MANIFEST, PKGMODE_PROJECT, PRESERVE_ALL, PRESERVE_ALL_INSTALLED, PRESERVE_DIRECT, PRESERVE_NONE, PRESERVE_SEMVER, PRESERVE_TIERED, PRESERVE_TIERED_INSTALLED, Pkg, PreserveLevel, Registry, UPLEVEL_MAJOR, UPLEVEL_MINOR, UPLEVEL_PATCH

[jariji]

Also for all modules M https://github.com/JuliaLang/julia/issues/52581

• [ ] M.include
• [ ] M.eval

[stevengj]

(Note that the module-specific include and eval are not marked as public or exported, so I would put them in a separate category.)

[nsajko]

Seems to duplicate issues #26919 and #31202. Also related: #19529, #51335.

[nsajko]

Note that the module-specific include and eval are not marked as public or exported

Sidenote: presumably they should be public.

[fonsp]

Markdown.@md_str is also exported and undocumented, but it did not show up in this list.

[LilithHafner]

I'm guessing this list was created with a buggy Base.Docs.undocumented_names implementation

[Bhavay-2001]

Hi @stevengj , can I work on this issue? Thanks

[LilithHafner]

You can work on this issue! Add some docstrings to names on this list that you understand and make a pull request :)

[Bhavay-2001]

Hi @LilithHafner, adding docstring means writing documentation for the keywords on the list like Base, Base.Sys etc right? Can you please explain what kind of documentation is to be written? Do we have to write about what they do?

[stevengj]

Markdown.@md_str is also exported and undocumented, but it did not show up in this list.

That will be fixed by #52727.

[LilithHafner]

When you type ?sort into a REPL, the docstring is printed. You can see how and where it is defined by running @less sort([]) and scrolling up a bit.

A good workflow might be

• Read https://docs.julialang.org/en/v1/manual/documentation/
• Clone the Julia repo
• Pick a name (e.g. Markdown.html), ideally, but not necessarily, one that you are already familiar with or have used
• Find out what it does
• Create a docstring for the generic function and, only if you think it is worth the extra verbosity, add docstrings for some additional methods of that name.

[fonsp]

@Bhavay-2001 an example of a PR that contributes to this issue is the one I made: https://github.com/JuliaLang/julia/pull/52733 , maybe that's helpful to look at! Thanks for your interest and we look forward to your first PR!

[RichieWilynnton]

Hello, I also am interested in working in this issue, can I also work on this?

[stevengj]

Anyone can work on this.

I'll try to keep the list up to date, and link a PR if someone is already working on it even if it's not done yet, so that people don't duplicate efforts. You can also look at linked PRs for examples.

(The easiest ones to start on would probably be the ones where only the module name itself is missing a docstring, e.g. Libdl.)

[RichieWilynnton]

#52791
Hello, I am a beginner who is slowly figuring out the codebase via doing the documentation. I did a small edit in this pr and for some reason the build took a very long time (8 hrs) and failed. Can anyone please review this and help me understand why this is happening? Are the builds supposed to take this long?

[stevengj]

Running the full test suite can take a long time, since it's running on lots of platforms using servers that have lots of jobs queued. And it's not uncommon to have unrelated failures on a few platforms (e.g. due to network glitches or unrelated bugs that arise on unusual systems) — if the error messages look unrelated to the code you edited, I wouldn't worry about it. One of the Julia maintainers will look at the test logs before merging.

[RichieWilynnton]

Excuse me for the disturbance, but I have a quick question regarding our workflow. I've recently added a PR (#52825) for the Libdl module documentation and was wondering if it's necessary or preferred to link every PR to its corresponding issue in the discussion?

I want to ensure my contributions align well with the team's practices. Thank you very much!

[LilithHafner]

If a PR addresses an issue, I typically link to that issue in the original post of the PR (e.g. "Fixes part of #52725") in addition to briefly describing the change.

GitHub automatically inserts a back-link from the issue that is linked to back to the linking issue so I don't usually create a manual back-link.

[jam-khan]

Hi, I am a beginner to open-source and Julia. I have added docstrings for the TOML module and created my first PR. Thanks!

[RichieWilynnton]

#52876 This is my latest PR with the REPL documentation

[danik292]

I look for this 😉

[jam-khan]

Hi, I have added the following PRs: #52913 for Artifacts #52914 for Dates: adjust

Thanks!

[aravindh-krishnamoorthy]

I'll update the LA documentation in #52934

[tecosaur]

I've got a WIP package that might be of interest here: https://github.com/tecosaur/CheckDoc.jl

[aravindh-krishnamoorthy]

I find the initiative by OP and @tecosaur commendable. However, I'd like to take this opportunity to point out an observation during my work on the linear algebra (LA) documentation PR.

The LA package defines its own version of copyto! in matmul.jl ${}^1$ with a different signature than what is documented in multidimentional.jl.

The signatures are as follows:

# multidimensional.jl
function copyto!(dest::AbstractArray{T1,N}, Rdest::CartesianIndices{N}, src::AbstractArray{T2,N}, Rsrc::CartesianIndices{N}) where {T1,T2,N}

# matmul.jl
function copyto!(B::AbstractVecOrMat, ir_dest::AbstractUnitRange{Int}, jr_dest::AbstractUnitRange{Int}, tM::AbstractChar, M::AbstractVecOrMat, ir_src::AbstractUnitRange{Int}, jr_src::AbstractUnitRange{Int})

The DocString for the multidimensional.jl version offers no insight into the LA variant. However, the function exported by LA is marked documented by the check because of the matching function name.

I understand the complexity involved in checking for this and other problem cases as it's hard to distinguish between an "overloaded" version of a documented function vs an incompatible new declaration. Unfortunately, I have no solution to offer either.

Footnotes: ${}^1$ Nothing special about the particular commit, it's just the most recent commit as of now.

[tecosaur]

Related to that, something I'm currently working on in CheckDoc.jl is matching up signatures to function methods. This should be helpful for the problem you describe, if it can be done well enough (unfortunately it's going to need to rely on heuristics).

[AllHailTheSheep]

Hello, I'm a beginner am and looking to open a PR to add the docstrings for the logging symbols. Would that just be adding the docstrings for these symbols as they are defined in /stdlib/Logging.jl here to /base/logging.jl here?

Thanks!

[inkydragon]

Would that just be adding the docstrings for these symbols as they are defined in /stdlib/Logging.jl here to /base/logging.jl here?

I think so, since the symbols in Logging.jl are just aliases in base.

[danik292]

@stevengj what should good docstring have?

[stevengj]

@danik292, see the Writing Documentation section of the manual.