Documenting all exports from Base

[mbauman]

It'd be nice to make sure that all our exports are documented and make sense for the 1.0 release. This is a fairly daunting list, but it is a task that's easily parallelizable and can be tackled incrementally.

There are two classes of undocumented thing.

• It's just plain undocumented. Add documentation!
• It's a callable thing and all its methods live within deprecated.jl. In this case, we probably want to @deprecate_binding the binding itself so packages that extend these methods won't be totally surprised when the binding gets removed in 1.0.

I've written a quick and simple script that identifies these two cases and spits out the list. Please feel free to jump in and add PRs to resolve these as you are able! Just be bold and go for it!

julia> searchdocs(mod) = searchdocs!(Any[], Bool[], mod)
       function searchdocs!(objs, isalldep, mod, seen=Set())
           mod in seen && return
           push!(seen, mod)
           for name in names(mod)
               isdefined(mod, name) || continue
               Base.isdeprecated(mod, name) && continue
               b = getfield(mod, name)
               docs = Base.Docs.doc(Base.Docs.Binding(mod, name))
               if startswith(string(docs), "No documentation found")
                   push!(objs, string(mod, '.', name))
                   push!(isalldep, !isempty(methods(b)) && all(x->occursin("deprecated", something(functionloc(x)[1],"")), methods(b)))
               end
               b isa Module && searchdocs!(objs, isalldep, b, seen)
           end
           objs, isalldep
       end
searchdocs! (generic function with 2 methods)

julia> objs, isalldep = searchdocs(Main)

julia> println("### Undocumented exports")
       foreach(x->println("* [ ] `", x, '`'), objs[.!isalldep])
       println("### Undocumented exports that are entirely deprecated")
       foreach(x->println("* [ ] `", x, '`'), objs[isalldep])

Undocumented exports (including module exports)

• Base.Broadcast.dotview
• Base.CanonicalIndexError
• Base.CapturedException
• Base.Docs.@var
• Base.InvalidStateException
• Base.Libc.FILE
• Base.Sys.CPU_NAME
• Base.Sys.JIT
• Base.Sys.cpu_info
• Base.Sys.cpu_summary
• Core.ConcurrencyViolationError
• Core.Exception
• Core.GlobalRef
• Core.IO
• Core.LineNumberNode
• Core.Method
• Core.SegmentationFault
• Core.TypeVar
• Core.WeakRef
• Core.getglobal
• Core.setglobal!
• Core.VecElement
• Core.DataType (Add inline documentation for Type and DataType. #24561)
• Core.Type (Add inline documentation for Type and DataType. #24561)
• Base (docstrings for Base, Core, Main, Module #31131)
• Base.AbstractDict (Document AbstractDict and AbstractSet #31206)
• Base.AbstractDisplay(Document AbstractDisplay #31229)
• Base.AbstractSet (Document AbstractDict and AbstractSet #31206)
• Base.Libc.systemsleep (doc systemsleep #31518)
• Base.Meta.isexpr (Docstrings for quot, isexpr and show_sexpr #31246)
• Base.Meta.quot (Docstrings for quot, isexpr and show_sexpr #31246)
• Base.Meta.show_sexpr (Docstrings for quot, isexpr and show_sexpr #31246)
• Base.SubArray (Document the SubArray type #32931)
• Base.Sys.CPU_NAME (Document some exported Sys CPU stuff #31204)
• Base.Sys.cpu_info (Document some exported Sys CPU stuff #31204)
• Base.Sys.cpu_summary (Document some exported Sys CPU stuff #31204)
• Base.Sys.free_memory ( Doc free_memory and total_memory #31297)
• Base.Sys.total_memory ( Doc free_memory and total_memory #31297)
• Core (docstrings for Base, Core, Main, Module #31131)
• Core.Main
• Core.Module (docstrings for Base, Core, Main, Module #31131)
• Core.QuoteNode
• Main.Main (docstrings for Base, Core, Main, Module #31131)
• Base.@MIME_str
• Base.@b_str
• Base.DEPOT_PATH
• Base.Enum
• Base.IOStream
• Base.MIME
• Main.InteractiveUtils
• Base.=> (document some undocumented exports #27107)
• Base.@big_str (Doc some string parsing macros #28067)
• Base.@cmd (Doc the at-cmd macro #28062)
• Base.@int128_str (Doc some string parsing macros #28067)
• Base.@uint128_str (Doc some string parsing macros #28067)
• Base.@v_str (document some undocumented exports #27107)
• Base.AbstractVecOrMat (document some undocumented exports #27107)
• Base.Base (document some undocumented exports #27107)
• Base.Broadcast (document some undocumented exports #27107)
• Base.Broadcast.Broadcast (document some undocumented exports #27107)
• Base.Broadcast.dotview (not exported)
• Base.CompositeException (Document CompositeException and add more xrefs #28061)
• Base.DFT (deprecated in Remove the FFTW bindings from Base #21956)
• Base.DFT.DFT (deprecated in Remove the FFTW bindings from Base #21956)
• Base.GC (document some undocumented exports #27107)
• Base.GC.GC (document some undocumented exports #27107)
• Base.Inf64 (document some undocumented exports #27107)
• Base.NaN64 (document some undocumented exports #27107)
• Base.Operators (deprecated in remove Operators module #22251)
• Base.Operators.Operators (deprecated in remove Operators module #22251)
• Base.Sys.free_memory (not exported)
• Base.Sys.total_memory (not exported)
• Base.VecOrMat (document some undocumented exports #27107)
• Base.VersionNumber (document some undocumented exports #27107)
• Base.bin (deprecated in deprecate bin, oct, dec, hex, and base in favor of string and keyword args #25804)
• Base.dec (deprecated in deprecate bin, oct, dec, hex, and base in favor of string and keyword args #25804)
• Base.hex (deprecated in deprecate bin, oct, dec, hex, and base in favor of string and keyword args #25804)
• Base.indmax (deprecated to argmax in Rename indmin and indmax to argmin and argmax #25654)
• Base.oct (deprecated in deprecate bin, oct, dec, hex, and base in favor of string and keyword args #25804)
• Base.substrides
• Base.∉ (document some undocumented exports #27107)
• Base.∋ (document some undocumented exports #27107)
• Base.∌ (document some undocumented exports #27107)
• Base.⊇ (document some undocumented exports #27107)
• Base.⊈ (document some undocumented exports #27107)
• Base.⊉ (document some undocumented exports #27107)
• Base.⊊ (document some undocumented exports #27107)
• Base.⊋ (document some undocumented exports #27107)
• Main.Base
• Base.@big_str
• Base.@generated
• Base.@int128_str
• Base.@uint128_str
• Base.AbstractRange (Doc missing range exports #28115)
• Base.AbstractUnitRange (Doc missing range exports #28115)
• Base.CompositeException (Document CompositeException and add more xrefs #28061)
• Base.Cstring (Doc Cstring and Cwstring #28396)
• Base.Cwstring (Doc Cstring and Cwstring #28396)
• Base.DenseMatrix (Document DenseArrays and Dims #28080)
• Base.DenseVecOrMat (Document DenseArrays and Dims #28080)
• Base.DenseVector (Document DenseArrays and Dims #28080)
• Base.Dims (Document DenseArrays and Dims #28080)
• Base.IndexCartesian (Doc IndexLinear and IndexCartesian #28476)
• Base.IndexLinear (Doc IndexLinear and IndexCartesian #28476)
• Base.InsertionSort (Doc sorting algos #28514)
• Base.LinRange (Doc missing range exports #28115)
• Base.MergeSort (Doc sorting algos #28514)
• Base.OrdinalRange (Doc missing range exports #28115)
• Base.PartialQuickSort (Doc sorting algos #28514)
• Base.QuickSort (Doc sorting algos #28514)
• Base.RawFD (Add docs for RawFD #28410)
• Base.Regex
• Base.RoundFromZero (Docs for RoundFromZero and some xrefs #28427)
• Base.StepRange (Doc missing range exports #28115)
• Base.StridedArray (Added docs for the StridedArrays and fixed a doctest fail #28144)
• Base.StridedMatrix (Added docs for the StridedArrays and fixed a doctest fail #28144)
• Base.StridedVecOrMat (Added docs for the StridedArrays and fixed a doctest fail #28144)
• Base.StridedVector (Added docs for the StridedArrays and fixed a doctest fail #28144)
• Base.UnitRange (Doc missing range exports #28115)
• Base.done (deprecated to iterate)
• Core.DenseArray (Document DenseArrays and Dims #28080)
• Main.ans (special keyword doc)

Edit: updated to remove the entirely-deprecated section

[JeffBezanson]

It's not straightforward to add a @deprecate_binding for every deprecated function, since the replacement is often non-trivial and/or doesn't have a name.

[fredrikekre]

You don't get line numbers for @deprecate_binding either, usually just the module, which makes it almost impossible to track down location of where you need to update your code.

[KristofferC]

I think

  Base.bin
  Base.dec
  Base.hex
  Base.oct

will be unexported after the deprecations are removed?

[mbauman]

Those are missing a deprecation in intfuncs:

julia> methods(bin)
# 5 methods for generic function "bin":
...
[2] bin(x::Unsigned, pad::Int64, neg::Bool) in Base at intfuncs.jl:570
...

That's why they're getting put in the first list. Perhaps those methods should be deprecated, too?

[KristofferC]

I thought they are just used internally for string of a number?

[mbauman]

Ah, sure enough. The script isn't checking base/exports.jl — it's just using the method locations as a proxy for entirely deprecated. I suppose as long as those methods are undocumented that's okay, but it does strike me as a bit of a gray zone.

[fredrikekre]

In this case, we probably want to @deprecate_binding the binding itself so packages that extend these methods won't be totally surprised when the binding gets removed in 1.0.

You don't get line numbers for @deprecate_binding either, usually just the module, which makes it almost impossible to track down location of where you need to update your code.

Would it be possible to print a warning when extending a totally deprecated function? If so, we can add another argument to @deprecate.