From 38b81562d79dfa44816bd3ce5b249cad87904587 Mon Sep 17 00:00:00 2001
From: "Steven G. Johnson" <stevenj@alum.mit.edu>
Date: Thu, 4 Jan 2024 16:44:38 -0500
Subject: [PATCH] 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
https://github.com/JuliaLang/julia/pull/52413#issuecomment-1876266678

cc @jariji, @LilithHafner

---------

Co-authored-by: Lilith Orion Hafner <lilithhafner@gmail.com>
---
 NEWS.md           |  2 +-
 base/docs/Docs.jl | 19 ++++++++++---------
 test/docs.jl      |  9 +++++++--
 3 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 7b4cda50b8985..cee80f892ec2a 100644
--- a/NEWS.md
+++ b/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]).
diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
index 5e7126f47c28d..e5974d3280308 100644
--- a/base/docs/Docs.jl
+++ b/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
 
diff --git a/test/docs.jl b/test/docs.jl
index 7ebef8832cd69..190bcaee6adf5 100644
--- a/test/docs.jl
+++ b/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