add tests for undocumented symbols (#52723)

Following #52413 by @jariji and the discussion in #51174, this adds
tests to ensure that there are no undocumented *(= lacking docstrings)*
public symbols in any documented module.

Many of the tests are broken — we have a lot of undocumented exports. In
such cases I added both a `@test_broken` and a `@test` to ensure that
there are no additional regressions added in the future.

~~(This PR may have to be updated when
#52413 (comment) is
fixed, i.e. when ~~#52727~~ #52743 is merged.)~~ Has been updated.

---------

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

Author: stevengj

base/docs/Docs.jl

@@ -650,11 +650,37 @@ function loaddocs(docs::Vector{Core.SimpleVector})
     nothing
 end
 
+# FIXME: formatdoc, parsedoc, apropos, and doc are defined here (but only doc is exported)
+# for historical reasons (#25738), but are *implemented* in REPL/src/docview.jl, while
+# apropos is *exported* by InteractiveUtils and doc is exported by Docs.  Seems
+# like a more sensible refactoring should be possible.
+
 function formatdoc end
 function parsedoc end
+
+"""
+    apropos([io::IO=stdout], pattern::Union{AbstractString,Regex})
+
+Search available docstrings for entries containing `pattern`.
+
+When `pattern` is a string, case is ignored. Results are printed to `io`.
+
+`apropos` can be called from the help mode in the REPL by wrapping the query in double quotes:
+```
+help?> "pattern"
+```
+"""
 function apropos end
-function doc end
 
+"""
+    Docs.doc(binding, sig)
+
+Return all documentation that matches both `binding` and `sig`.
+
+If `getdoc` returns a non-`nothing` result on the value of the binding, then a
+dynamic docstring is returned instead of one based on the binding itself.
+"""
+function doc end
 
 """
     Docs.hasdoc(mod::Module, sym::Symbol)::Bool

base/libc.jl

@@ -45,6 +45,11 @@ show(io::IO, fd::RawFD) = print(io, "RawFD(", bitcast(UInt32, fd), ')')  # avoid
 
 # Wrapper for an OS file descriptor (for Windows)
 if Sys.iswindows()
+    @doc """
+        WindowsRawSocket
+
+    Primitive type which wraps the native Windows file `HANDLE`.
+    """
     primitive type WindowsRawSocket sizeof(Ptr) * 8 end # On Windows file descriptors are HANDLE's and 64-bit on 64-bit Windows
     WindowsRawSocket(handle::Ptr{Cvoid}) = bitcast(WindowsRawSocket, handle)
     WindowsRawSocket(handle::WindowsRawSocket) = handle

stdlib/Artifacts/test/runtests.jl

@@ -261,3 +261,9 @@ end
     @test length(Base.manifest_names) == 2n # there are two manifest names per project name
     @test length(Base.preferences_names) == n
 end
+
+@testset "Docstrings" begin
+    undoc = Docs.undocumented_names(Artifacts)
+    @test_broken isempty(undoc)
+    @test undoc == [:Artifacts]
+end

stdlib/Base64/test/runtests.jl

@@ -1,7 +1,8 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
 using Test, Random
-import Base64:
+using Base64:
+    Base64,
     Base64EncodePipe,
     base64encode,
     Base64DecodePipe,
@@ -142,3 +143,7 @@ end
         @test String(base64decode(splace(longEncodedText))) == longDecodedText
     end
 end
+
+@testset "Docstrings" begin
+    @test isempty(Docs.undocumented_names(Base64))
+end

stdlib/CRC32c/test/runtests.jl

@@ -77,3 +77,7 @@ end
 crc32c_sw(io::IO, crc::UInt32=0x00000000) = crc32c_sw(io, typemax(Int64), crc)
 test_crc32c(crc32c)
 test_crc32c(crc32c_sw)
+
+@testset "Docstrings" begin
+    @test isempty(Docs.undocumented_names(CRC32c))
+end

stdlib/Dates/test/runtests.jl

@@ -2,8 +2,16 @@
 
 module DateTests
 
+using Test, Dates
+
 for file in readlines(joinpath(@__DIR__, "testgroups"))
     include(file * ".jl")
 end
 
+@testset "Docstrings" begin
+    undoc = Docs.undocumented_names(Dates)
+    @test_broken isempty(undoc)
+    @test undoc == [:adjust]
+end
+
 end

stdlib/FileWatching/test/runtests.jl

@@ -447,4 +447,10 @@ rm(dir)
     include("pidfile.jl")
 end
 
+@testset "Docstrings" begin
+    undoc = Docs.undocumented_names(FileWatching)
+    @test_broken isempty(undoc)
+    @test undoc == [:FDWatcher, :FileMonitor, :FolderMonitor, :PollingFileWatcher]
+end
+
 end # testset

stdlib/Future/test/runtests.jl

@@ -2,3 +2,7 @@
 
 using Test
 using Future
+
+@testset "Docstrings" begin
+    @test isempty(Docs.undocumented_names(Future))
+end

stdlib/InteractiveUtils/test/runtests.jl

@@ -724,3 +724,9 @@ end
 end
 
 @test Base.infer_effects(sin, (Int,)) == InteractiveUtils.@infer_effects sin(42)
+
+@testset "Docstrings" begin
+    undoc = Docs.undocumented_names(InteractiveUtils)
+    @test_broken isempty(undoc)
+    @test undoc == [:InteractiveUtils]
+end

stdlib/LibGit2/test/runtests.jl

@@ -1,6 +1,11 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-using Test
+using Test, LibGit2
+
 @testset verbose=true "LibGit2 $test" for test in eachline(joinpath(@__DIR__, "testgroups"))
     include("$test.jl")
 end
+
+@testset "Docstrings" begin
+    @test isempty(Docs.undocumented_names(LibGit2))
+end