Merge pull request #20142 from JuliaLang/jmm/dynamic_doc

RFC: Add support for dynamic doc strings

base/docs/Docs.jl

@@ -238,12 +238,28 @@ end
 # Docstring lookup.
 # =================
 
+"""
+ getdoc(x::T, sig) -> String
+
+Return the dynamic docstring associated with object `x`, or `nothing` to use
+the binding's documentation.
+"""
+getdoc(x, sig) = getdoc(x)
+getdoc(x) = nothing
+
 """
  Docs.doc(binding, sig)
 
 Returns 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(binding::Binding, sig::Type = Union{})
+ if defined(binding)
+ result = getdoc(resolve(binding), sig)
+ result === nothing || return result
+ end
  results, groups = DocStr[], MultiDoc[]
  # Lookup `binding` and `sig` for matches in all modules of the docsystem.
  for mod in modules

test/docs.jl

@@ -922,3 +922,17 @@ let save_color = Base.have_color
  eval(Base, :(have_color = $save_color))
  end
 end
+
+
+# Dynamic docstrings
+
+type DynamicDocType
+ x
+end
+
+Base.Docs.getdoc(d::DynamicDocType) = Base.Markdown.parse(d.x)
+
+dynamic_test = DynamicDocType("test 1")
+@test docstrings_equal(@doc(dynamic_test), doc"test 1")
+dynamic_test.x = "test 2"
+@test docstrings_equal(@doc(dynamic_test), doc"test 2")