From 42094740f8f48213c07d9a807d85f5d24cf6c27f Mon Sep 17 00:00:00 2001
From: jariji <96840304+jariji@users.noreply.github.com>
Date: Tue, 5 Dec 2023 10:24:32 -0800
Subject: [PATCH] Add `Docs.hasdoc` function (#52139)

Add helper method `Docs.hasdoc` to facilitate automated testing of
whether documentation exists.

Closes: https://github.com/JuliaLang/julia/issues/51174.
Co-authored-by: Steven G. Johnson <stevenj@mit.edu>
---
 NEWS.md                         |  1 +
 base/docs/Docs.jl               | 20 ++++++++++++++++++++
 doc/src/manual/documentation.md |  3 +++
 test/docs.jl                    |  7 +++++++
 4 files changed, 31 insertions(+)

diff --git a/NEWS.md b/NEWS.md
index fed308639b9a3..b5dbc894a3aeb 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -70,6 +70,7 @@ New library features
 * `replace(string, pattern...)` now supports an optional `IO` argument to
   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]).
 
 Standard library changes
 ------------------------
diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
index 4ca384361c4e3..87b4a45c4dc80 100644
--- a/base/docs/Docs.jl
+++ b/base/docs/Docs.jl
@@ -655,4 +655,24 @@ function parsedoc end
 function apropos end
 function doc end
 
+
+"""
+    Docs.hasdoc(mod::Module, sym::Symbol)::Bool
+
+Return `true` if `sym` in `mod` has a docstring and `false` otherwise.
+"""
+hasdoc(mod::Module, sym::Symbol) = hasdoc(Docs.Binding(mod, sym))
+function hasdoc(binding::Docs.Binding, sig::Type = Union{})
+    # this function is based on the Base.Docs.doc method implemented
+    # in REPL/src/docview.jl.  TODO: refactor and unify these methods.
+    defined(binding) && !isnothing(getdoc(resolve(binding), sig)) && return true
+    for mod in modules
+        dict = meta(mod; autoinit=false)
+        !isnothing(dict) && haskey(dict, binding) && return true
+    end
+    alias = aliasof(binding)
+    return alias == binding ? false : hasdoc(alias, sig)
+end
+
+
 end
diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index 4c724e1deaaeb..169b27ead15f8 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -19,6 +19,9 @@ environments provide a way to access documentation directly:
 - In [Juno](https://junolab.org) using `Ctrl-J, Ctrl-D` will show the documentation for the object
   under the cursor.
 
+
+`Docs.hasdoc(module, name)::Bool` tells whether a name has a docstring.
+
 ## Writing Documentation
 
 Julia enables package developers and users to document functions, types and other objects easily
diff --git a/test/docs.jl b/test/docs.jl
index 401759cd7cdb0..1b26c9670e180 100644
--- a/test/docs.jl
+++ b/test/docs.jl
@@ -69,6 +69,13 @@ $$latex literal$$
 """
 function break_me_docs end
 
+
+# `hasdoc` returns `true` on a name with a docstring.
+@test Docs.hasdoc(Base, :map)
+# `hasdoc` returns `false` on a name without a docstring.
+@test !isdefined(Base, :_this_name_doesnt_exist_) && !Docs.hasdoc(Base, :_this_name_doesnt_exist_)
+@test isdefined(Base, :_typed_vcat) && !Docs.hasdoc(Base, :_typed_vcat)
+
 # issue #11548
 
 module ModuleMacroDoc