From e40aa41c7b739438947abb4f8579ac3761cfe5f4 Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 10:41:10 +0100
Subject: [PATCH 01/10] feat: add test for undocumented public names

---
 Project.toml                             |  2 +-
 docs/make.jl                             |  1 +
 docs/src/undocumented_names.md           |  7 +++++++
 src/Aqua.jl                              | 20 +++++++++++++++++-
 src/undocumented_names.jl                | 26 ++++++++++++++++++++++++
 test/pkgs/PkgWithUndocumentedNames.jl    | 20 ++++++++++++++++++
 test/pkgs/PkgWithoutUndocumentedNames.jl | 18 ++++++++++++++++
 test/test_undocumented_names.jl          | 25 +++++++++++++++++++++++
 8 files changed, 117 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/undocumented_names.md
 create mode 100644 src/undocumented_names.jl
 create mode 100644 test/pkgs/PkgWithUndocumentedNames.jl
 create mode 100644 test/pkgs/PkgWithoutUndocumentedNames.jl
 create mode 100644 test/test_undocumented_names.jl

diff --git a/Project.toml b/Project.toml
index 69e7850a..fc9a0db3 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,7 +1,7 @@
 name = "Aqua"
 uuid = "4c88cf16-eb10-579e-8560-4a9242c79595"
 authors = ["Takafumi Arakaki <aka.tkf@gmail.com> and contributors"]
-version = "0.8.9"
+version = "0.8.10"
 
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
diff --git a/docs/make.jl b/docs/make.jl
index 07de9cf2..d681a5d0 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -29,6 +29,7 @@ makedocs(;
             "deps_compat.md",
             "piracies.md",
             "persistent_tasks.md",
+            "undocumented_names.md",
         ],
         "release-notes.md",
     ],
diff --git a/docs/src/undocumented_names.md b/docs/src/undocumented_names.md
new file mode 100644
index 00000000..fa6ce36b
--- /dev/null
+++ b/docs/src/undocumented_names.md
@@ -0,0 +1,7 @@
+# Undocumented names
+
+## [Test function](@id test_undocumented_names)
+
+```@docs
+Aqua.test_undocumented_names
+```
diff --git a/src/Aqua.jl b/src/Aqua.jl
index bc4f00df..ff5bd4a1 100644
--- a/src/Aqua.jl
+++ b/src/Aqua.jl
@@ -1,6 +1,13 @@
+"""
+    Aqua
+
+Package providing Auto QUality Assurance for other Julia packages.
+
+GitHub repository: https://github.com/JuliaTesting/Aqua.jl
+"""
 module Aqua
 
-using Base: PkgId, UUID
+using Base: Docs, PkgId, UUID
 using Pkg: Pkg, TOML, PackageSpec
 using Test
 
@@ -23,6 +30,7 @@ include("stale_deps.jl")
 include("deps_compat.jl")
 include("piracies.jl")
 include("persistent_tasks.jl")
+include("undocumented_names.jl")
 
 """
     test_all(testtarget::Module)
@@ -37,6 +45,7 @@ Run the following tests:
 * [`test_deps_compat(testtarget)`](@ref test_deps_compat)
 * [`test_piracies(testtarget)`](@ref test_piracies)
 * [`test_persistent_tasks(testtarget)`](@ref test_persistent_tasks)
+* [`test_undocumented_names(testtarget)`](@ref test_undocumented_names)
 
 The keyword argument `\$x` (e.g., `ambiguities`) can be used to
 control whether or not to run `test_\$x` (e.g., `test_ambiguities`).
@@ -52,6 +61,7 @@ passed to `\$x` to specify the keyword arguments for `test_\$x`.
 - `deps_compat = true`
 - `piracies = true`
 - `persistent_tasks = true`
+- `undocumented_names = true`
 """
 function test_all(
     testtarget::Module;
@@ -63,6 +73,7 @@ function test_all(
     deps_compat = true,
     piracies = true,
     persistent_tasks = true,
+    undocumented_names = true,
 )
     @testset "Method ambiguity" begin
         if ambiguities !== false
@@ -105,6 +116,13 @@ function test_all(
             test_persistent_tasks(testtarget; askwargs(persistent_tasks)...)
         end
     end
+    @testset "Undocumented names" begin
+        if undocumented_names !== false
+            isempty(askwargs(undocumented_names)) ||
+                error("Keyword arguments not supported")
+            test_undocumented_names(testtarget; askwargs(undocumented_names)...)
+        end
+    end
 end
 
 end # module
diff --git a/src/undocumented_names.jl b/src/undocumented_names.jl
new file mode 100644
index 00000000..871797d5
--- /dev/null
+++ b/src/undocumented_names.jl
@@ -0,0 +1,26 @@
+"""
+    test_undocumented_names(module::Module)
+
+Test that all public names in `module` have a docstring (including the module itself).
+
+!!! warning
+    For Julia versions before 1.11, this does not test anything.
+"""
+function test_undocumented_names(m::Module)
+    @static if VERSION >= v"1.11"
+        names = Docs.undocumented_names(m)
+    else
+        names = Symbol[]
+    end
+    if !isempty(names)
+        printstyled(
+            stderr,
+            "Undocumented names detected:\n";
+            bold = true,
+            color = Base.error_color(),
+        )
+        show(stderr, MIME"text/plain"(), names)
+        println(stderr)
+    end
+    @test isempty(names)
+end
diff --git a/test/pkgs/PkgWithUndocumentedNames.jl b/test/pkgs/PkgWithUndocumentedNames.jl
new file mode 100644
index 00000000..45a56a98
--- /dev/null
+++ b/test/pkgs/PkgWithUndocumentedNames.jl
@@ -0,0 +1,20 @@
+module PkgWithUndocumentedNames
+
+"""
+    documented_function
+"""
+function documented_function end
+
+function undocumented_function end
+
+"""
+    DocumentedStruct
+"""
+struct DocumentedStruct end
+
+struct UndocumentedStruct end
+
+export documented_function, DocumentedStruct
+export undocumented_function, UndocumentedStruct
+
+end  # module
diff --git a/test/pkgs/PkgWithoutUndocumentedNames.jl b/test/pkgs/PkgWithoutUndocumentedNames.jl
new file mode 100644
index 00000000..46b8b5a5
--- /dev/null
+++ b/test/pkgs/PkgWithoutUndocumentedNames.jl
@@ -0,0 +1,18 @@
+"""
+    PkgWithoutUndocumentedNames
+"""
+module PkgWithoutUndocumentedNames
+
+"""
+    documented_function
+"""
+function documented_function end
+
+"""
+    DocumentedStruct
+"""
+struct DocumentedStruct end
+
+export documented_function, DocumentedStruct
+
+end  # module
diff --git a/test/test_undocumented_names.jl b/test/test_undocumented_names.jl
new file mode 100644
index 00000000..aed94980
--- /dev/null
+++ b/test/test_undocumented_names.jl
@@ -0,0 +1,25 @@
+module TestUndocumentedNames
+
+include("preamble.jl")
+
+import PkgWithUndocumentedNames
+import PkgWithoutUndocumentedNames
+
+@testset begin
+    # Pass
+    results = @testtestset begin
+        Aqua.test_undocumented_names(PkgWithoutUndocumentedNames)
+    end
+    @test length(results) == (VERSION >= v"1.11")
+    @test results[1] isa Test.Pass
+    # Fail
+    results = @testtestset begin
+        Aqua.test_undocumented_names(PkgWithUndocumentedNames)
+    end
+    @test length(results) == (VERSION >= v"1.11")
+    @test results[1] isa Test.Fail
+    # Logs
+    @test_nowarn Aqua.test_undocumented_names(PkgWithoutUndocumentedNames)
+end
+
+end  # module

From fe267d35f9c97913e8bc6eb85ea4d57641f58e91 Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 10:45:20 +0100
Subject: [PATCH 02/10] Update Changelog

---
 CHANGELOG.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d5ed66b..8f8ead04 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Version [v0.8.10] - unreleased
+
+### Changed
+
+- Add `test_undocumented_names` to verify that all public symbols have docstrings (including the module itself). ([#313])
+
 
 ## Version [v0.8.9] - 2024-10-15
 

From 0fdd06f0f6debdd0871b90f6b7c459e583b1eb2e Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 10:49:40 +0100
Subject: [PATCH 03/10] Fix v1.10

---
 test/test_undocumented_names.jl | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/test_undocumented_names.jl b/test/test_undocumented_names.jl
index aed94980..2ac03365 100644
--- a/test/test_undocumented_names.jl
+++ b/test/test_undocumented_names.jl
@@ -10,14 +10,14 @@ import PkgWithoutUndocumentedNames
     results = @testtestset begin
         Aqua.test_undocumented_names(PkgWithoutUndocumentedNames)
     end
-    @test length(results) == (VERSION >= v"1.11")
+    @test length(results) == 1
     @test results[1] isa Test.Pass
     # Fail
     results = @testtestset begin
         Aqua.test_undocumented_names(PkgWithUndocumentedNames)
     end
-    @test length(results) == (VERSION >= v"1.11")
-    @test results[1] isa Test.Fail
+    @test length(results) == 1
+    @test results[1] isa (VERSION >= v"1.11" ? Test.Fail : Test.Pass)
     # Logs
     @test_nowarn Aqua.test_undocumented_names(PkgWithoutUndocumentedNames)
 end

From e03668326d56984ca6f5e5fb3c0fc456864657ff Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 10:50:46 +0100
Subject: [PATCH 04/10] Include Aqua docstring in manual

---
 docs/src/index.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/src/index.md b/docs/src/index.md
index 22509efc..94081fe0 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -11,6 +11,10 @@ Aqua.jl provides functions to run a few automatable checks for Julia packages:
 * There are no "obvious" type piracies.
 * The package does not create any persistent Tasks that might block precompilation of dependencies.
 
+```@docs
+Aqua
+```
+
 ## Quick usage
 
 Call `Aqua.test_all(YourPackage)` from the REPL, e.g.,

From d4585c9d1192524288aaa50b2c36c1eac683aa0d Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 10:59:00 +0100
Subject: [PATCH 05/10] No test on 1.10

---
 src/undocumented_names.jl       |  2 +-
 test/test_undocumented_names.jl | 28 ++++++++++++++++------------
 2 files changed, 17 insertions(+), 13 deletions(-)

diff --git a/src/undocumented_names.jl b/src/undocumented_names.jl
index 871797d5..089d205e 100644
--- a/src/undocumented_names.jl
+++ b/src/undocumented_names.jl
@@ -9,6 +9,7 @@ Test that all public names in `module` have a docstring (including the module it
 function test_undocumented_names(m::Module)
     @static if VERSION >= v"1.11"
         names = Docs.undocumented_names(m)
+        @test isempty(names)
     else
         names = Symbol[]
     end
@@ -22,5 +23,4 @@ function test_undocumented_names(m::Module)
         show(stderr, MIME"text/plain"(), names)
         println(stderr)
     end
-    @test isempty(names)
 end
diff --git a/test/test_undocumented_names.jl b/test/test_undocumented_names.jl
index 2ac03365..e53e2d9b 100644
--- a/test/test_undocumented_names.jl
+++ b/test/test_undocumented_names.jl
@@ -5,21 +5,25 @@ include("preamble.jl")
 import PkgWithUndocumentedNames
 import PkgWithoutUndocumentedNames
 
-@testset begin
-    # Pass
-    results = @testtestset begin
-        Aqua.test_undocumented_names(PkgWithoutUndocumentedNames)
-    end
+# Pass
+results = @testtestset begin
+    Aqua.test_undocumented_names(PkgWithoutUndocumentedNames)
+end
+if VERSION >= v"1.11"
     @test length(results) == 1
     @test results[1] isa Test.Pass
-    # Fail
-    results = @testtestset begin
-        Aqua.test_undocumented_names(PkgWithUndocumentedNames)
-    end
+else
+    @test length(results) == 0
+end
+# Fail
+results = @testtestset begin
+    Aqua.test_undocumented_names(PkgWithUndocumentedNames)
+end
+if VERSION >= v"1.11"
     @test length(results) == 1
-    @test results[1] isa (VERSION >= v"1.11" ? Test.Fail : Test.Pass)
-    # Logs
-    @test_nowarn Aqua.test_undocumented_names(PkgWithoutUndocumentedNames)
+    @test results[1] isa Test.Fail
+else
+    @test length(results) == 0
 end
 
 end  # module

From 4df5e8b62b561553784547abae2d78f9c24dc4ef Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 12:40:20 +0100
Subject: [PATCH 06/10] Exclude module name

---
 src/Aqua.jl               | 7 -------
 src/undocumented_names.jl | 2 +-
 2 files changed, 1 insertion(+), 8 deletions(-)

diff --git a/src/Aqua.jl b/src/Aqua.jl
index ff5bd4a1..14996685 100644
--- a/src/Aqua.jl
+++ b/src/Aqua.jl
@@ -1,10 +1,3 @@
-"""
-    Aqua
-
-Package providing Auto QUality Assurance for other Julia packages.
-
-GitHub repository: https://github.com/JuliaTesting/Aqua.jl
-"""
 module Aqua
 
 using Base: Docs, PkgId, UUID
diff --git a/src/undocumented_names.jl b/src/undocumented_names.jl
index 089d205e..9471ea21 100644
--- a/src/undocumented_names.jl
+++ b/src/undocumented_names.jl
@@ -9,7 +9,7 @@ Test that all public names in `module` have a docstring (including the module it
 function test_undocumented_names(m::Module)
     @static if VERSION >= v"1.11"
         names = Docs.undocumented_names(m)
-        @test isempty(names)
+        @test isempty(names) || (only(names) == nameof(m))
     else
         names = Symbol[]
     end

From 05bf3ec7fc127a8a8b0e92ab621edacb21139af3 Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 12:44:21 +0100
Subject: [PATCH 07/10] Filter names

---
 src/undocumented_names.jl | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/undocumented_names.jl b/src/undocumented_names.jl
index 9471ea21..2fe848fd 100644
--- a/src/undocumented_names.jl
+++ b/src/undocumented_names.jl
@@ -9,18 +9,19 @@ Test that all public names in `module` have a docstring (including the module it
 function test_undocumented_names(m::Module)
     @static if VERSION >= v"1.11"
         names = Docs.undocumented_names(m)
-        @test isempty(names) || (only(names) == nameof(m))
+        names_filtered = filter(n -> n != nameof(m), names)
+        @test isempty(names_filtered)
     else
-        names = Symbol[]
+        names_filtered = Symbol[]
     end
-    if !isempty(names)
+    if !isempty(names_filtered)
         printstyled(
             stderr,
             "Undocumented names detected:\n";
             bold = true,
             color = Base.error_color(),
         )
-        show(stderr, MIME"text/plain"(), names)
+        show(stderr, MIME"text/plain"(), names_filtered)
         println(stderr)
     end
 end

From 9e39dc94c7f45d09035b4855ca09562940846d7e Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 12:52:42 +0100
Subject: [PATCH 08/10] Fixes

---
 docs/src/index.md               |  4 ----
 src/undocumented_names.jl       | 11 +++++------
 test/test_undocumented_names.jl |  2 ++
 3 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/docs/src/index.md b/docs/src/index.md
index 94081fe0..22509efc 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -11,10 +11,6 @@ Aqua.jl provides functions to run a few automatable checks for Julia packages:
 * There are no "obvious" type piracies.
 * The package does not create any persistent Tasks that might block precompilation of dependencies.
 
-```@docs
-Aqua
-```
-
 ## Quick usage
 
 Call `Aqua.test_all(YourPackage)` from the REPL, e.g.,
diff --git a/src/undocumented_names.jl b/src/undocumented_names.jl
index 2fe848fd..16584184 100644
--- a/src/undocumented_names.jl
+++ b/src/undocumented_names.jl
@@ -8,20 +8,19 @@ Test that all public names in `module` have a docstring (including the module it
 """
 function test_undocumented_names(m::Module)
     @static if VERSION >= v"1.11"
-        names = Docs.undocumented_names(m)
-        names_filtered = filter(n -> n != nameof(m), names)
-        @test isempty(names_filtered)
+        undocumented_names = filter(n -> n != nameof(m), Docs.undocumented_names(m))
+        @test isempty(undocumented_names)
     else
-        names_filtered = Symbol[]
+        undocumented_names = Symbol[]
     end
-    if !isempty(names_filtered)
+    if !isempty(undocumented_names)
         printstyled(
             stderr,
             "Undocumented names detected:\n";
             bold = true,
             color = Base.error_color(),
         )
-        show(stderr, MIME"text/plain"(), names_filtered)
+        show(stderr, MIME"text/plain"(), undocumented_names)
         println(stderr)
     end
 end
diff --git a/test/test_undocumented_names.jl b/test/test_undocumented_names.jl
index e53e2d9b..83f2f1f5 100644
--- a/test/test_undocumented_names.jl
+++ b/test/test_undocumented_names.jl
@@ -16,9 +16,11 @@ else
     @test length(results) == 0
 end
 # Fail
+println("### Expected output START ###")
 results = @testtestset begin
     Aqua.test_undocumented_names(PkgWithUndocumentedNames)
 end
+println("### Expected output END ###")
 if VERSION >= v"1.11"
     @test length(results) == 1
     @test results[1] isa Test.Fail

From 2a3c4aa4ca79988914905451e14965e8674a0fe0 Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 13:08:34 +0100
Subject: [PATCH 09/10] Docstring

---
 src/undocumented_names.jl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/undocumented_names.jl b/src/undocumented_names.jl
index 16584184..5d28a50b 100644
--- a/src/undocumented_names.jl
+++ b/src/undocumented_names.jl
@@ -1,7 +1,7 @@
 """
     test_undocumented_names(module::Module)
 
-Test that all public names in `module` have a docstring (including the module itself).
+Test that all public names in `module` have a docstring (not including the module itself).
 
 !!! warning
     For Julia versions before 1.11, this does not test anything.

From 83150f4d8c62dd775d49f17b4e5c6502506c4038 Mon Sep 17 00:00:00 2001
From: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
Date: Sun, 24 Nov 2024 13:31:47 +0100
Subject: [PATCH 10/10] Bump version to v0.9.0

---
 CHANGELOG.md | 2 +-
 Project.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f8ead04..c7a50697 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Version [v0.8.10] - unreleased
+## Version [v0.9.0] - unreleased
 
 ### Changed
 
diff --git a/Project.toml b/Project.toml
index fc9a0db3..357bf268 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,7 +1,7 @@
 name = "Aqua"
 uuid = "4c88cf16-eb10-579e-8560-4a9242c79595"
 authors = ["Takafumi Arakaki <aka.tkf@gmail.com> and contributors"]
-version = "0.8.10"
+version = "0.9.0"
 
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"