Variable docstring synchronization between command line help and manual

[omus]

Uses new Sphinx directive "variable" to synchronize docstrings for variables with the manual. I created several new docstrings based upon the descriptions in the manual.

Requires JuliaLang/JuliaDoc#22 (merged)
Partially addresses #16303.

[omus]

Currently nothing, ANY, JULIA_HOME, and CPU_CORES are in the helpdb file. I should be able to get JULIA_HOME and CPU_CORES out of helpdb. I'm not sure where nothing or ANY should go as they aren't explicitly defined in base. Suggestions are welcome.

[omus]

cc @MichaelHatherly: I've modified genstdlib.jl

[MichaelHatherly]

in the helpdb file

Perhaps in basedocs.jl? That's where other docstrings without declarations have been going. Note that instead of :nothing etc. you can just put nothing. No need to quote the object, it should have the same effect.

[tkelman]

A VersionNumber object

[omus]

Thanks. Good catch.

[tkelman]

further down it looks like you were just porting over the existing rst description, so consider this an enhancement :)

[omus]

I have updated all the docstrings for constants/variables listed in stdlib/constants. Additionally I noticed most of the "See also" references were broken so I fixed that as well.

I'm sure I have missed some constants that should be updated but I think this PR has modified enough files ;)

[MichaelHatherly]

Rather than having 3 similar docstrings perhaps something like the following?

const MS_ASYNC = 1
const MS_INVALIDATE = 2
const MS_SYNC = 4

@doc """
    MS_ASYNC
    MS_INVALIDATE
    MS_SYNC

Enum constants for [`msync`](:func:`msync`). See your platform man page for details.
(not available on Windows).
""" ->
(MS_ASYNC, MS_INVALIDATE, MS_SYNC)

and then adjust the signature in the rst docs accordingly.

(@doc needed since this is inside a @unix_only block, not toplevel.)

[omus]

How do I get this to match up with the manual?

WARNING: duplicate signature found for 'Base.MS_INVALIDATE' in module 'Base':

    MS_ASYNC
    MS_SYNC
    MS_INVALIDATE

WARNING: duplicate signature found for 'Base.MS_ASYNC' in module 'Base':

    MS_ASYNC
    MS_SYNC
    MS_INVALIDATE

[MichaelHatherly]

Adding a

.. variable:: MS_ASYNC
              MS_INVALIDATE
              MS_SYNC

declaration should be sufficient I think.

[omus]

Seems so obvious now... I still get the warnings however.

[MichaelHatherly]

Actually, that's probably a bug in genstdlib, since the docstrings are the same object rather than different docstrings that happen to have the same signature. I'll try track that one down.

[MichaelHatherly]

Could you try applying this diff and see if the duplicate warnings are gone?

diff --git a/doc/genstdlib.jl b/doc/genstdlib.jl
index b03a146..85e28fb 100644
--- a/doc/genstdlib.jl
+++ b/doc/genstdlib.jl
@@ -111,7 +111,7 @@ function loaddocs!(state::State, mod, binding::Binding, typesig, docstr)
     markdown = Base.Docs.parsedoc(docstr)
     if validdocstr(markdown)
         code = rstrip(markdown.content[1].code)
-        if haskey(state.validdocs, code)
+        if haskey(state.validdocs, code) && state.validdocs[code][3] !== docstr
             code = indent(code)
             warn("duplicate signature found for '$binding' in module '$mod':\n\n$code\n")
             state.errorlevel = 2

[omus]

Patch does fix the duplicate signature warnings. Should I include the patch as part of this PR?

[MichaelHatherly]

Yes, please do. I don't want to hold up your PR with different one line PR :)