expand Docs.undocumented_names to include all public symbols (#52743)

Expands the semantics of `Docs.undocumented_names` to include all public
symbols, as described in
#52413 (comment)

cc @jariji, @LilithHafner

---------

Co-authored-by: Lilith Orion Hafner <[email protected]>

NEWS.md

@@ -84,7 +84,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.undocumented_names(module; all)` returns a module's undocumented names ([#52413]).
+* New function `Docs.undocumented_names(module)` returns a module's undocumented public names ([#52413]).
 * Passing an `IOBuffer` as a stdout argument for `Process` spawn now works as
   expected, synchronized with `wait` or `success`, so a `Base.BufferStream` is
   no longer required there for correctness to avoid data races ([#52461]).

base/docs/Docs.jl

@@ -676,18 +676,19 @@ end
 
 
 """
-    undocumented_names(mod::Module; all=false)
+    undocumented_names(mod::Module; private=false)
 
-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. Names are returned in sorted order.
+Return a sorted vector of undocumented symbols in `module` (that is, lacking docstrings).
+`private=false` (the default) returns only identifiers declared with `public` and/or
+`export`, whereas `private=true` returns all symbols in the module (excluding
+compiler-generated hidden symbols starting with `#`).
 
-See also: [`names`](@ref), [`Docs.hasdoc`](@ref), [`Base.isidentifier`](@ref).
+See also: [`names`](@ref), [`Docs.hasdoc`](@ref), [`Base.ispublic`](@ref).
 """
-function undocumented_names(mod::Module; all::Bool=false)
-    filter!(names(mod; all)) do sym
-        !hasdoc(mod, sym) && Base.isidentifier(sym)
+function undocumented_names(mod::Module; private::Bool=false)
+    filter!(names(mod; all=true)) do sym
+        !hasdoc(mod, sym) && !startswith(string(sym), '#') &&
+            (private || Base.ispublic(mod, sym))
     end
 end
 

test/docs.jl

@@ -79,7 +79,12 @@ function break_me_docs end
 "This module has names without documentation."
 module _ModuleWithUndocumentedNames
 export f
+public ⨳, @foo
 f() = 1
+g() = 2
+⨳(a,b) = a * b
+macro foo(); nothing; end
+⊕(a,b) = a + b
 end
 
 "This module has some documentation."
@@ -90,9 +95,9 @@ f() = 1
 g() = 2
 end
 
-@test Docs.undocumented_names(_ModuleWithUndocumentedNames) == [:f]
+@test Docs.undocumented_names(_ModuleWithUndocumentedNames) == [Symbol("@foo"), :f, :⨳]
 @test isempty(Docs.undocumented_names(_ModuleWithSomeDocumentedNames))
-@test Docs.undocumented_names(_ModuleWithSomeDocumentedNames; all=true) == [:eval, :g, :include]
+@test Docs.undocumented_names(_ModuleWithSomeDocumentedNames; private=true) == [:eval, :g, :include]
 
 
 # issue #11548