Add Docs.hasdoc function (#52139)

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

Closes: #51174.
Co-authored-by: Steven G. Johnson <[email protected]>

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
 ------------------------

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

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

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