Add Docs.undocumented_names

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

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

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
 

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