Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documenting all exports from the standard libraries #31202

Closed
mbauman opened this issue Feb 28, 2019 · 7 comments
Closed

Documenting all exports from the standard libraries #31202

mbauman opened this issue Feb 28, 2019 · 7 comments
Labels
docs This change adds or pertains to documentation good first issue Indicates a good issue for first-time contributors to Julia help wanted Indicates that a maintainer wants help on an issue or pull request stdlib Julia's standard library

Comments

@mbauman
Copy link
Member

mbauman commented Feb 28, 2019 •
edited by vtjnash
Loading

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)
@mbauman mbauman added docs This change adds or pertains to documentation help wanted Indicates that a maintainer wants help on an issue or pull request stdlib Julia's standard library labels Feb 28, 2019
@mbauman mbauman mentioned this issue Feb 28, 2019
Merged
@kshyatt kshyatt added the good first issue Indicates a good issue for first-time contributors to Julia label Feb 28, 2019
@eulerkochy eulerkochy mentioned this issue Mar 1, 2019
Merged
@kshyatt kshyatt mentioned this issue Mar 1, 2019
Merged
This was referenced Mar 6, 2019
Merged
Merged
Merged
@karthikrangasai karthikrangasai mentioned this issue Mar 28, 2019
Closed
@dkarrasch
Copy link
Member

@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!

@dkarrasch dkarrasch mentioned this issue Apr 5, 2019
Merged
jch8ri added a commit to jch8ri/julia that referenced this issue May 6, 2019
@jch8ri
updated some docs for issue JuliaLang#31202
7081354
jch8ri added a commit to jch8ri/julia that referenced this issue May 9, 2019
@jch8ri
updated documentation for issue JuliaLang#31202
e5ab90c
@chrisvwx chrisvwx mentioned this issue Jul 5, 2019
Closed
@asinghvi17
Copy link
Contributor

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

@mbauman
Copy link
Member Author

mbauman commented Aug 7, 2019

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

@mbauman mbauman mentioned this issue Aug 14, 2019
Merged
@KristofferC
Copy link
Member

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.

@matbesancon matbesancon mentioned this issue Nov 8, 2019
Merged
@dkarrasch dkarrasch mentioned this issue Nov 9, 2019
Merged
mrdofu added a commit to mrdofu/julia that referenced this issue Jun 29, 2020
@mrdofu
added documentation for Dates.TimeZone, Dates.UTC
0ee0f72 
see JuliaLang#31202
@mrdofu mrdofu mentioned this issue Jun 29, 2020
Merged
mrdofu added a commit to mrdofu/julia that referenced this issue Jul 7, 2020
@mrdofu
added documentation for Dates.TimeZone, Dates.UTC
1bdafab 
see JuliaLang#31202
@mrdofu mrdofu mentioned this issue Jul 17, 2020
Merged
@chris-b1 chris-b1 mentioned this issue Jul 23, 2020
Merged
simeonschaub pushed a commit to simeonschaub/julia that referenced this issue Aug 11, 2020
@mrdofu @simeonschaub
added documentation for Dates.TimeZone, Dates.UTC
a8b22c7 
see JuliaLang#31202
@vtjnash
Copy link
Member

vtjnash commented Apr 20, 2021 •
edited by ViralBShah
Loading

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

  • Dates.adjust
  • Distributed.check_same_host
  • FileWatching.FDWatcher
  • FileWatching.FileMonitor
  • FileWatching.FolderMonitor
  • FileWatching.PollingFileWatcher
  • LinearAlgebra.LAPACKException
  • LinearAlgebra.RankDeficientException
  • LinearAlgebra.copy_transpose!
  • Markdown.@doc_str
  • Markdown.@md_str
  • Markdown.html
  • Markdown.latex
  • Pkg.@pkg_str
  • Pkg.PKGMODE_MANIFEST
  • Pkg.PKGMODE_PROJECT
  • Pkg.PRESERVE_ALL
  • Pkg.PRESERVE_DIRECT
  • Pkg.PRESERVE_NONE
  • Pkg.PRESERVE_SEMVER
  • Pkg.PRESERVE_TIERED
  • Pkg.PreserveLevel
  • Pkg.UPLEVEL_MAJOR
  • Pkg.UPLEVEL_MINOR
  • Pkg.UPLEVEL_PATCH
  • REPL.AbstractREPL
  • REPL.BasicREPL
  • REPL.LineEditREPL
  • REPL.StreamREPL
  • SHA.HMAC_CTX
  • SHA.hmac_sha1
  • SHA.hmac_sha224
  • SHA.hmac_sha256
  • SHA.hmac_sha2_224
  • SHA.hmac_sha2_256
  • SHA.hmac_sha2_384
  • SHA.hmac_sha2_512
  • SHA.hmac_sha384
  • SHA.hmac_sha3_224
  • SHA.hmac_sha3_256
  • SHA.hmac_sha3_384
  • SHA.hmac_sha3_512
  • SHA.hmac_sha512
  • Serialization.AbstractSerializer
  • Serialization.Serializer

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

  • CompilerSupportLibraries_jll.libgfortran
  • CompilerSupportLibraries_jll.libgomp
  • CompilerSupportLibraries_jll.libstdcxx
  • GMP_jll.libgmp
  • GMP_jll.libgmpxx
  • LLVMLibUnwind_jll.llvmlibunwind
  • LibCURL_jll.libcurl
  • LibGit2_jll.libgit2
  • LibSSH2_jll.libssh2
  • LibUV_jll.libuv
  • LibUnwind_jll.libunwind
  • MPFR_jll.libmpfr
  • MbedTLS_jll.libmbedcrypto
  • MbedTLS_jll.libmbedtls
  • MbedTLS_jll.libmbedx509
  • OpenBLAS_jll.libopenblas
  • OpenLibm_jll.libopenlibm
  • PCRE2_jll.libpcre2_8
  • SuiteSparse_jll.libamd
  • SuiteSparse_jll.libbtf
  • SuiteSparse_jll.libcamd
  • SuiteSparse_jll.libccolamd
  • SuiteSparse_jll.libcholmod
  • SuiteSparse_jll.libcolamd
  • SuiteSparse_jll.libklu
  • SuiteSparse_jll.libldl
  • SuiteSparse_jll.librbio
  • SuiteSparse_jll.libspqr
  • SuiteSparse_jll.libsuitesparseconfig
  • SuiteSparse_jll.libumfpack
  • Zlib_jll.libz

@Seelengrab Seelengrab mentioned this issue Nov 1, 2021
Merged
@Seelengrab Seelengrab mentioned this issue Sep 7, 2023
Closed
This was referenced Nov 18, 2023
Closed
Closed
Closed
This was referenced Jan 4, 2024
Open
Closed
@nsajko
Copy link
Contributor

nsajko commented Jan 4, 2024

Related issues: #19529, #51335.

@mbauman
Copy link
Member Author

mbauman commented Jan 4, 2024

Superseded by #52725

@mbauman mbauman closed this as not planned Won't fix, can't repro, duplicate, stale Jan 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs This change adds or pertains to documentation good first issue Indicates a good issue for first-time contributors to Julia help wanted Indicates that a maintainer wants help on an issue or pull request stdlib Julia's standard library
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
7 participants
@mbauman @vtjnash @kshyatt @KristofferC @nsajko @dkarrasch @asinghvi17