Add Docs.undocumented_names

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 ([#52413]).
 
 Standard library changes
 ------------------------

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

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
 

test/docs.jl

@@ -76,6 +76,28 @@ 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 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)
+
+
 # issue #11548
 
 module ModuleMacroDoc