search

JuliaLang / julia

The Julia Programming Language
https://julialang.org/
MIT License
45.58k stars 5.48k forks source link

Documenting all exports from the standard libraries #31202

Closed mbauman closed 9 months ago

mbauman commented 5 years ago

Adding docstrings to all exports from Base has been a great success (#26919)! We are about 80% done there (and I just moved the goalposts — we had been close to 95% prior to that). That's awesome — thanks everyone who participated. Now let's move on to the standard libraries!

searchdocs(mod) = searchdocs!(Any[], mod)
function searchdocs!(objs, 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))
        end
        b isa Module && searchdocs!(objs, b, seen)
    end
    objs
end
ms = []
for M in [filter(f->f[1] in 'A':'Z' && !occursin(r"[-.]", f) && f != "Makefile", readdir("stdlib")); "Pkg"]
    @eval import $(Symbol(M))
    @eval append!(ms, searchdocs($(Symbol(M))))
end
foreach(x->println("* [ ] `", x, '`'), ms)
dkarrasch commented 5 years ago

@mbauman or @kshyatt, could you please mark those commands which are covered by PRs? It should be the twelve month constants and there abbreviations (#31218), the four SparseArrays.XYZ (#31286), and all factorization docstrings (#31284). Just to avoid redundant work as has happened already. Many thanks!

asinghvi17 commented 5 years ago

Shouldn't the Markdown types also be documented, since they have constructors?

mbauman commented 5 years ago

This list is only enumerating the exported names — those are the official public (and stable) APIs and are the biggest priorities.

KristofferC commented 5 years ago

Shouldn't the Markdown types also be documented, since they have constructors?

It is also very questionable if the Markdown stuff is considered public. And if not, I don't think we want to make it public by documenting it + putting it in the manual. It doesn't feel up to snuff in terms of robustness and quality that we want.

vtjnash commented 3 years ago

There's been a lot of progress. Someone could probably finish this list in an afternoon:

Though the jll libraries are new, they can be ignored:

nsajko commented 9 months ago

Related issues: #19529, #51335.

mbauman commented 9 months ago

Superseded by #52725