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
• Base.Sys: CPU_NAME, JIT, cpu_info, cpu_summary (add missing docstrings for Base.Sys  #52777)
• Base.Filesystem:
  • File, Filesystem, cptree, futime, rename, sendfile, unlink
  • 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 (Add docstring to constants in Base.Filesystem #53247)
• Base.Docs: @var
• Base.Broadcast: dotview
• Base.Order: DirectOrdering, ForwardOrdering, Order, ordtype
• Base.Sort: Algorithm, SMALL_ALGORITHM (add docstring for SMALL_ALGORITHM #53807), SMALL_THRESHOLD, Sort

Standard Library:

• Libdl: Libdl (Added documentation to libdl module #52825)
• TOML: TOML (Add docstring for TOML stdlib module #52834)
• Artifacts: Artifacts (Added docstring for Artifacts.jl #52913)
• Dates: adjust (Add docstring for Dates.adjust #52914)
• Unicode: Unicode ([RFC:] Docstring for Unicode module #52761)
• Markdown: @doc_str, @md_str, html, latex (Docstring for Markdown.html and Markdown.latex #52733 and [Markdown] added doc string for @md_str string literal #52606)
• Serialization: AbstractSerializer, Serializer
• REPL: AbstractREPL, BasicREPL, LineEditREPL, StreamREPL (Added documentation for all repl types #52876)
• Printf: Printf (Documentation for "Printf" Module #52791)
• InteractiveUtils: InteractiveUtils (Add docstring for InteractiveUtils module #53206)
• Profile: Allocs (Adding docstring for the Allocs #53559)
• LinearAlgebra: ColumnNorm, LAPACKException, NoPivot, RankDeficientException, RowMaximum, RowNonZero, copy_transpose! (Documentation update for LinearAlgebra functions #52934)
• Logging: AboveMaxLevel, BelowMinLevel
• FileWatching: FDWatcher, FileMonitor, FolderMonitor, PollingFileWatcher
• SparseArrays: fkeep! (Move fkeep! docstring to the right function JuliaSparse/SparseArrays.jl#503)
• Tar: Tar (Add docstring for Tar module JuliaIO/Tar.jl#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 #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: #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.

[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.

[danik292]

@stevengj thx

[danik292]

@stevengj
I have two qestions on you.
Firstly, what SMALL_ALGORYHM is?
Secondy Where i should put docstring for this? I dont see any definition or something like this.

thx

[LilithHafner]

Did someone mention sorting? Hello.

Firstly, what SMALL_ALGORYHM is?

Something that maybe shouldn't have been exported from the Sort module. But it is, so that makes it public. It's the default algorithm for sorting small arrays. rn it's an alias for InsertionSort, but it could well point to an unrolled merge sort, a sorting network, or some other algorithm good for small vectors in the future.

Secondy Where i should put docstring for this? I dont see any definition or something like this.

It's defined at or near line 815 of base/sort.jl

shell> ag "const SMALL_ALGORITHM"
base/sort.jl
815:const SMALL_ALGORITHM = InsertionSortAlg()

[danik292]

Secondy Where i should put docstring for this? I dont see any definition or something like this.

It's defined at or near line 815 of base/sort.jl

shell> ag "const SMALL_ALGORITHM"
base/sort.jl
815:const SMALL_ALGORITHM = InsertionSortAlg()

wow how you do this??
@LilithHafner

[LilithHafner]

1. Install https://github.com/ggreer/the_silver_searcher
2. cd to a local clone of the Julia repo
3. Run that command

[jariji]

What about Core? #53971 found Core.Method exported but undocumented.

[stevengj]

Thanks, @jariji, I added an item for Core

[danik292]

Hello @stevengj I am going to the Write docstring for

small_thershold

[LilithHafner]

Thanks, though there's no need to at someone to announce that

[danik292]

Thanks, though there's no need to at someone to announce that

Well I am announcing it because I don't want to do it to see someone alredy done it

[stevengj]

Just open a draft PR and link to this issue, and we will link back to it from here. PRs aren't getting opened so frequently that you are likely to see someone else jumping in at the same time on the same docstring.

[danik292]

@stevengj small_thereshold is constant witch seys biggest number of membrs of a list is still internaly counted as small.

[jariji]

Stdlib submodules may be missing docstrings: SparseArrays.CHOLMOD.Factor is exported but has no docstring.

[jariji]

Do we also need to write docstrings for all the types that are returned by public functions of public types? Since how is a user supposed to handle an undocumented value? E.g.

julia> typeof(reshape(rand(2,2)', :))
Base.ReshapedArray{Float64, 1, Adjoint{Float64, Matrix{Float64}}, Tuple{Base.MultiplicativeInverses.SignedMultiplicativeInverse{Int64}}}

help?> Base.ReshapedArray
  No documentation found.