From c2e1707b6d85b89f98cbaae662eeaaf74a0023e0 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Tue, 5 Dec 2023 14:14:00 -0800 Subject: [PATCH 01/14] Add Docs.check_documented --- NEWS.md | 1 + base/docs/Docs.jl | 11 +++++++++++ doc/src/manual/documentation.md | 3 ++- 3 files changed, 14 insertions(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index b5dbc894a3aeb..fe76e8ca60488 100644 --- a/NEWS.md +++ b/NEWS.md @@ -71,6 +71,7 @@ New library features write the output to a stream rather than returning a string ([#48625]). * `sizehint!(s, n)` now supports an optional `shrink` argument to disable shrinking ([#51929]). * New function `Docs.hasdoc(module, symbol)` tells whether a name has a docstring ([#52139]). +* New function `Docs.check_documented(module; all)` checks whether a module's names are documented. Standard library changes ------------------------ diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 87b4a45c4dc80..35b824cfc32f7 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -675,4 +675,15 @@ function hasdoc(binding::Docs.Binding, sig::Type = Union{}) end +""" + check_documented(mod::Module; all=false) + +Check all names in the module are documented. `all` determines which names are checked, +following the behavior of `names(mod; all)`. +""" +function check_documented(mod::Module; all=false) + nodocs = filter!(sym -> !hasdoc(mod, sym), names(mod; all)) + isempty(nodocs) || error("missing docstrings in $mod: $nodocs") +end + end diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index 169b27ead15f8..c07b910735c61 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -20,7 +20,8 @@ environments provide a way to access documentation directly: under the cursor. -`Docs.hasdoc(module, name)::Bool` tells whether a name has a docstring. +`Docs.hasdoc(module, name)::Bool` tells whether a name has a docstring. `Docs.check_documented(module; all)` +checks that the names in a module are documented. ## Writing Documentation From cb6100044eb01a1882d211191642b94dc9ef957c Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Tue, 5 Dec 2023 14:16:51 -0800 Subject: [PATCH 02/14] Update news --- NEWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NEWS.md b/NEWS.md index fe76e8ca60488..2deb9f090481e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -71,7 +71,7 @@ New library features write the output to a stream rather than returning a string ([#48625]). * `sizehint!(s, n)` now supports an optional `shrink` argument to disable shrinking ([#51929]). * New function `Docs.hasdoc(module, symbol)` tells whether a name has a docstring ([#52139]). -* New function `Docs.check_documented(module; all)` checks whether a module's names are documented. +* New function `Docs.check_documented(module; all)` checks whether a module's names are documented ([#52413]). Standard library changes ------------------------ From 26a795a574e108d488b683fec89b3d42a3832cd7 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Tue, 5 Dec 2023 14:24:42 -0800 Subject: [PATCH 03/14] Add tests --- test/docs.jl | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/test/docs.jl b/test/docs.jl index 1b26c9670e180..a916a57a6d9b1 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -76,6 +76,30 @@ function break_me_docs end @test !isdefined(Base, :_this_name_doesnt_exist_) && !Docs.hasdoc(Base, :_this_name_doesnt_exist_) @test isdefined(Base, :_typed_vcat) && !Docs.hasdoc(Base, :_typed_vcat) +"This module has names without documentation." +module _ModuleWithUndocumentedNames +export f +f() = 1 +end + +"This module has some documentation." +module _ModuleWithSomeDocumentedNames +export f +"f() is 1." +f() = 1 +g() = 2 +end + +# Error for undocumented names. +@test_throws Error Docs.check_documented(_ModuleWithUndocumentedNames) +# Pass for documented exported names. +@test isnothing(Docs.check_documented(_ModuleWithSomeDocumentedNames)) +# Error for undocumented unexported names when `all=true`. +@test_throws Docs.check_documented(_ModuleWithSomeDocumentedNames; all=true) + + + + # issue #11548 module ModuleMacroDoc From 19af2f07533557967f4bd758f6242b67e5869cb7 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Tue, 5 Dec 2023 18:38:13 -0800 Subject: [PATCH 04/14] update --- test/docs.jl | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/test/docs.jl b/test/docs.jl index a916a57a6d9b1..049370ef2f5d7 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -91,13 +91,11 @@ g() = 2 end # Error for undocumented names. -@test_throws Error Docs.check_documented(_ModuleWithUndocumentedNames) +@test_throws ErrorException Docs.check_documented(_ModuleWithUndocumentedNames) # Pass for documented exported names. @test isnothing(Docs.check_documented(_ModuleWithSomeDocumentedNames)) # Error for undocumented unexported names when `all=true`. -@test_throws Docs.check_documented(_ModuleWithSomeDocumentedNames; all=true) - - +@test_throws ErrorException Docs.check_documented(_ModuleWithSomeDocumentedNames; all=true) # issue #11548 From 6eae65952eda64ba10807d831cf1841be09e888f Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Tue, 5 Dec 2023 18:43:37 -0800 Subject: [PATCH 05/14] update --- test/docs.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/docs.jl b/test/docs.jl index 049370ef2f5d7..99b2015b75342 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -80,10 +80,10 @@ function break_me_docs end module _ModuleWithUndocumentedNames export f f() = 1 -end +end "This module has some documentation." -module _ModuleWithSomeDocumentedNames +module _ModuleWithSomeDocumentedNames export f "f() is 1." f() = 1 From 49b6fd1c55408c81af633612efea37050a24be89 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Wed, 6 Dec 2023 00:04:49 -0800 Subject: [PATCH 06/14] update --- base/docs/Docs.jl | 2 +- test/docs.jl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 35b824cfc32f7..d1c014936a556 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -678,7 +678,7 @@ end """ check_documented(mod::Module; all=false) -Check all names in the module are documented. `all` determines which names are checked, +Check all names in the module are documented. `all` determines which names are checked, following the behavior of `names(mod; all)`. """ function check_documented(mod::Module; all=false) diff --git a/test/docs.jl b/test/docs.jl index 99b2015b75342..6444bf3569530 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -93,7 +93,7 @@ end # Error for undocumented names. @test_throws ErrorException Docs.check_documented(_ModuleWithUndocumentedNames) # Pass for documented exported names. -@test isnothing(Docs.check_documented(_ModuleWithSomeDocumentedNames)) +@test Docs.check_documented(_ModuleWithSomeDocumentedNames) # Error for undocumented unexported names when `all=true`. @test_throws ErrorException Docs.check_documented(_ModuleWithSomeDocumentedNames; all=true) From b0b8b5796097de6a5f1a37b86d87808b6b71fff0 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Sun, 10 Dec 2023 13:57:46 -0800 Subject: [PATCH 07/14] Replace check_documented with undocumented_names --- NEWS.md | 2 +- base/docs/Docs.jl | 13 +++++++------ doc/src/manual/documentation.md | 4 ++-- test/docs.jl | 9 +++------ 4 files changed, 13 insertions(+), 15 deletions(-) diff --git a/NEWS.md b/NEWS.md index 2deb9f090481e..2d11e6a4e0888 100644 --- a/NEWS.md +++ b/NEWS.md @@ -71,7 +71,7 @@ New library features write the output to a stream rather than returning a string ([#48625]). * `sizehint!(s, n)` now supports an optional `shrink` argument to disable shrinking ([#51929]). * New function `Docs.hasdoc(module, symbol)` tells whether a name has a docstring ([#52139]). -* New function `Docs.check_documented(module; all)` checks whether a module's names are documented ([#52413]). +* New function `Docs.undocumented_names(module; all)` returns a module's undocumented names ([#52413]). Standard library changes ------------------------ diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index d1c014936a556..5b6defdf6aba4 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -676,14 +676,15 @@ end """ - check_documented(mod::Module; all=false) + undocumented_names(mod::Module; all=false) -Check all names in the module are documented. `all` determines which names are checked, -following the behavior of `names(mod; all)`. +Return the undocumented names in `module`. `all=false` returns only public names; +`all=true` also includes nonpublic names, following the behavior of [`names`](@ref). + +See also: [`names`](@ref), [`Docs.hasdoc`](@ref). """ -function check_documented(mod::Module; all=false) - nodocs = filter!(sym -> !hasdoc(mod, sym), names(mod; all)) - isempty(nodocs) || error("missing docstrings in $mod: $nodocs") +function undocumented_names(mod::Module; all=false) + filter(!hasdoc, names(mod; all)) end end diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md index c07b910735c61..58b1819e97372 100644 --- a/doc/src/manual/documentation.md +++ b/doc/src/manual/documentation.md @@ -20,8 +20,8 @@ environments provide a way to access documentation directly: under the cursor. -`Docs.hasdoc(module, name)::Bool` tells whether a name has a docstring. `Docs.check_documented(module; all)` -checks that the names in a module are documented. +`Docs.hasdoc(module, name)::Bool` tells whether a name has a docstring. `Docs.undocumented_names(module; all)` +returns the undocumented names in a module. ## Writing Documentation diff --git a/test/docs.jl b/test/docs.jl index 6444bf3569530..3247abdbe40a5 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -90,12 +90,9 @@ f() = 1 g() = 2 end -# Error for undocumented names. -@test_throws ErrorException Docs.check_documented(_ModuleWithUndocumentedNames) -# Pass for documented exported names. -@test Docs.check_documented(_ModuleWithSomeDocumentedNames) -# Error for undocumented unexported names when `all=true`. -@test_throws ErrorException Docs.check_documented(_ModuleWithSomeDocumentedNames; all=true) +@test Docs.undocumented_names(_ModuleWithUndocumentedNames) == [:f] +@test isempty(Docs.undocumented_names(_ModuleWithSomeDocumentedNames)) +@test Docs.undocumented_names(_ModuleWithSomeDocumentedNames; all=true) == [:g] # issue #11548 From ed7799e866bc4242001e52cd8931a8ccf6d05497 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Fri, 15 Dec 2023 17:37:31 -0800 Subject: [PATCH 08/14] update --- base/docs/Docs.jl | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 5b6defdf6aba4..b0c5059bd45fd 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -684,7 +684,9 @@ Return the undocumented names in `module`. `all=false` returns only public names See also: [`names`](@ref), [`Docs.hasdoc`](@ref). """ function undocumented_names(mod::Module; all=false) - filter(!hasdoc, names(mod; all)) + filter(names(mod; all)) do sym + !hasdoc(mod, sym) + end end end From 0369f6db8bea3e50596dcf9798ad17f731fb67ad Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Sat, 16 Dec 2023 11:02:41 -0800 Subject: [PATCH 09/14] Update base/docs/Docs.jl Co-authored-by: Steven G. Johnson --- base/docs/Docs.jl | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index b0c5059bd45fd..0453803ee80a6 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -678,8 +678,9 @@ end """ undocumented_names(mod::Module; all=false) -Return the undocumented names in `module`. `all=false` returns only public names; -`all=true` also includes nonpublic names, following the behavior of [`names`](@ref). +Return an array of undocumented symbols in `module` (that is, lacking docstrings). +`all=false` returns only exported symbols; whereas `all=true` also includes +non-exported symbols, following the behavior of [`names`](@ref). See also: [`names`](@ref), [`Docs.hasdoc`](@ref). """ From 935953f47eee4229201a5b685b9374cada7a4bdd Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Mon, 18 Dec 2023 14:59:39 -0800 Subject: [PATCH 10/14] Update base/docs/Docs.jl Co-authored-by: Steven G. Johnson --- base/docs/Docs.jl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 0453803ee80a6..960518bb28dae 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -684,9 +684,9 @@ non-exported symbols, following the behavior of [`names`](@ref). See also: [`names`](@ref), [`Docs.hasdoc`](@ref). """ -function undocumented_names(mod::Module; all=false) - filter(names(mod; all)) do sym - !hasdoc(mod, sym) +function undocumented_names(mod::Module; all::Bool=false, identifiers::Bool=true) + filter!(names(mod; all)) do sym + !hasdoc(mod, sym) && (!identifiers || Base.isidentifier(sym)) end end From d93fe130bfe47c4310b00a90f47f2254577720f8 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Mon, 18 Dec 2023 15:04:35 -0800 Subject: [PATCH 11/14] Update --- base/docs/Docs.jl | 7 ++++--- test/docs.jl | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 960518bb28dae..054e1d6e356a5 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -680,11 +680,12 @@ end Return an array of undocumented symbols in `module` (that is, lacking docstrings). `all=false` returns only exported symbols; whereas `all=true` also includes -non-exported symbols, following the behavior of [`names`](@ref). +non-exported symbols, following the behavior of [`names`](@ref). Only valid identifiers +are included. -See also: [`names`](@ref), [`Docs.hasdoc`](@ref). +See also: [`names`](@ref), [`Docs.hasdoc`](@ref), [`Base.isidentifier`](@ref). """ -function undocumented_names(mod::Module; all::Bool=false, identifiers::Bool=true) +function undocumented_names(mod::Module; all::Bool=false) filter!(names(mod; all)) do sym !hasdoc(mod, sym) && (!identifiers || Base.isidentifier(sym)) end diff --git a/test/docs.jl b/test/docs.jl index 3247abdbe40a5..7ebef8832cd69 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -92,7 +92,7 @@ end @test Docs.undocumented_names(_ModuleWithUndocumentedNames) == [:f] @test isempty(Docs.undocumented_names(_ModuleWithSomeDocumentedNames)) -@test Docs.undocumented_names(_ModuleWithSomeDocumentedNames; all=true) == [:g] +@test Docs.undocumented_names(_ModuleWithSomeDocumentedNames; all=true) == [:eval, :g, :include] # issue #11548 From 505d96fdacfdcc843b1c71dbc6ef7fd0ea594b2c Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Mon, 18 Dec 2023 15:11:35 -0800 Subject: [PATCH 12/14] Update --- base/docs/Docs.jl | 2 +- base/reflection.jl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 054e1d6e356a5..6f51cac948d38 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -681,7 +681,7 @@ end Return an array of undocumented symbols in `module` (that is, lacking docstrings). `all=false` returns only exported symbols; whereas `all=true` also includes non-exported symbols, following the behavior of [`names`](@ref). Only valid identifiers -are included. +are included. Names are returned in sorted order. See also: [`names`](@ref), [`Docs.hasdoc`](@ref), [`Base.isidentifier`](@ref). """ diff --git a/base/reflection.jl b/base/reflection.jl index 19dd289efbebf..720b1aa035864 100644 --- a/base/reflection.jl +++ b/base/reflection.jl @@ -79,7 +79,7 @@ Get an array of the public names of a `Module`, excluding deprecated names. If `all` is true, then the list also includes non-public names defined in the module, deprecated names, and compiler-generated names. If `imported` is true, then names explicitly imported from other modules -are also included. +are also included. Names are returned in sorted order. As a special case, all names defined in `Main` are considered \"public\", since it is not idiomatic to explicitly mark names from `Main` as public. From 4b66e8bc902826d75a5911c3f34257c6627ee12a Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Mon, 18 Dec 2023 19:00:50 -0800 Subject: [PATCH 13/14] Update --- base/docs/Docs.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 6f51cac948d38..c629518158265 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -687,7 +687,7 @@ See also: [`names`](@ref), [`Docs.hasdoc`](@ref), [`Base.isidentifier`](@ref). """ function undocumented_names(mod::Module; all::Bool=false) filter!(names(mod; all)) do sym - !hasdoc(mod, sym) && (!identifiers || Base.isidentifier(sym)) + !hasdoc(mod, sym) && Base.isidentifier(sym) end end From ecbcd75117b28fc08ba279e3f48b113bf9826ea2 Mon Sep 17 00:00:00 2001 From: jariji <96840304+jariji@users.noreply.github.com> Date: Tue, 19 Dec 2023 10:30:13 -0800 Subject: [PATCH 14/14] update --- base/docs/Docs.jl | 2 +- base/docs/utils.jl | 4 ++-- doc/src/base/base.md | 10 ++++++++++ 3 files changed, 13 insertions(+), 3 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index c629518158265..5e7126f47c28d 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -3,7 +3,7 @@ """ Docs -The `Docs` module provides the `@doc` macro which can be used to set and retrieve +The `Docs` module provides the [`@doc`](@ref) macro which can be used to set and retrieve documentation metadata for Julia objects. Please see the manual section on [documentation](@ref man-documentation) for more diff --git a/base/docs/utils.jl b/base/docs/utils.jl index 928dfde01ccf0..1ed576c7362ff 100644 --- a/base/docs/utils.jl +++ b/base/docs/utils.jl @@ -23,7 +23,7 @@ You can also use a stream for large amounts of data: `HTML` is currently exported to maintain backwards compatibility, but this export is deprecated. It is recommended to use - this type as `Docs.HTML` or to explicitly + this type as [`Docs.HTML`](@ref) or to explicitly import it from `Docs`. """ mutable struct HTML{T} @@ -81,7 +81,7 @@ You can also use a stream for large amounts of data: `Text` is currently exported to maintain backwards compatibility, but this export is deprecated. It is recommended to use - this type as `Docs.Text` or to explicitly + this type as [`Docs.Text`](@ref) or to explicitly import it from `Docs`. """ mutable struct Text{T} diff --git a/doc/src/base/base.md b/doc/src/base/base.md index c5d7320148e97..7172474b40b39 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -462,6 +462,16 @@ Base.functionloc(::Method) Base.@locals ``` +## Documentation +(See also the [documentation](@ref man-documentation) chapter.) +```@docs +Base.@doc +Docs.HTML +Docs.Text +Docs.hasdoc +Docs.undocumented_names +``` + ## Code loading ```@docs