From d4508cd1781cd96e80429956f41ee9dddb245597 Mon Sep 17 00:00:00 2001 From: Jon Malmaud Date: Thu, 19 Jan 2017 20:45:33 -0600 Subject: [PATCH 1/4] Add dynamic doc strings --- base/docs/Docs.jl | 20 +++++++++++++++++++- test/docs.jl | 14 ++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index afb0cdf3546a6..22bb2f4543adc 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -238,12 +238,27 @@ end # Docstring lookup. # ================= +""" + getdoc(x::T) -> String + +Return the dynamic docstring associated with object `x`. +""" +function getdoc end + """ Docs.doc(binding, sig) Returns all documentation that matches both `binding` and `sig`. + +If `getdoc` is defined 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 isdefined(binding.mod, binding.var) + var = getfield(binding.mod, binding.var) + if method_exists(getdoc, (typeof(var),)) + return Base.Markdown.parse(getdoc(var)) + end + end results, groups = DocStr[], MultiDoc[] # Lookup `binding` and `sig` for matches in all modules of the docsystem. for mod in modules @@ -285,7 +300,10 @@ end # Some additional convenience `doc` methods that take objects rather than `Binding`s. doc(obj::UnionAll) = doc(Base.unwrap_unionall(obj)) -doc(object, sig::Type = Union{}) = doc(aliasof(object, typeof(object)), sig) + +function doc(object, sig::Type = Union{}) + doc(aliasof(object, typeof(object)), sig) +end doc(object, sig...) = doc(object, Tuple{sig...}) """ diff --git a/test/docs.jl b/test/docs.jl index 02a5408f4262d..6cf639c5d6ad8 100644 --- a/test/docs.jl +++ b/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) = 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") From f8ae0edb9471d0a608ab5be4af4a730de25faafd Mon Sep 17 00:00:00 2001 From: Jon Malmaud Date: Sun, 22 Jan 2017 11:45:00 -0600 Subject: [PATCH 2/4] Pass sig to getdoc --- base/docs/Docs.jl | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 22bb2f4543adc..195d79113d9f5 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -239,25 +239,24 @@ end # ================= """ - getdoc(x::T) -> String + getdoc(x::T, sig) -> String -Return the dynamic docstring associated with object `x`. +Return the dynamic docstring associated with object `x`, or `nothing` to use the binding's documentation. """ -function getdoc end +getdoc(x, sig) = getdoc(x) +getdoc(x) = nothing """ Docs.doc(binding, sig) Returns all documentation that matches both `binding` and `sig`. -If `getdoc` is defined on the value of the binding, then a dynamic docstring is returned instead of one based on the binding itself. +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 isdefined(binding.mod, binding.var) - var = getfield(binding.mod, binding.var) - if method_exists(getdoc, (typeof(var),)) - return Base.Markdown.parse(getdoc(var)) - end + if defined(binding) + result = getdoc(resolve(binding), sig) + result === nothing || return Markdown.parse(result) end results, groups = DocStr[], MultiDoc[] # Lookup `binding` and `sig` for matches in all modules of the docsystem. @@ -300,10 +299,7 @@ end # Some additional convenience `doc` methods that take objects rather than `Binding`s. doc(obj::UnionAll) = doc(Base.unwrap_unionall(obj)) - -function doc(object, sig::Type = Union{}) - doc(aliasof(object, typeof(object)), sig) -end +doc(object, sig::Type = Union{}) = doc(aliasof(object, typeof(object)), sig) doc(object, sig...) = doc(object, Tuple{sig...}) """ From 20b462a24e843bd1469217b33286e152acbe92ad Mon Sep 17 00:00:00 2001 From: Jon Malmaud Date: Sun, 22 Jan 2017 17:29:56 -0600 Subject: [PATCH 3/4] Wrap getdoc docstring --- base/docs/Docs.jl | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 195d79113d9f5..38b3673c0fd1b 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -241,7 +241,8 @@ end """ getdoc(x::T, sig) -> String -Return the dynamic docstring associated with object `x`, or `nothing` to use the binding's documentation. +Return the dynamic docstring associated with object `x`, or `nothing` to use +the binding's documentation. """ getdoc(x, sig) = getdoc(x) getdoc(x) = nothing @@ -251,7 +252,8 @@ getdoc(x) = nothing 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. +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) From 31b24587526463ef5740e81a2d50069d0786614e Mon Sep 17 00:00:00 2001 From: Jon Malmaud Date: Tue, 24 Jan 2017 10:29:32 -0600 Subject: [PATCH 4/4] Don't call Markdown.parse --- base/docs/Docs.jl | 2 +- test/docs.jl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl index 38b3673c0fd1b..806f54d6e13cf 100644 --- a/base/docs/Docs.jl +++ b/base/docs/Docs.jl @@ -258,7 +258,7 @@ 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 Markdown.parse(result) + result === nothing || return result end results, groups = DocStr[], MultiDoc[] # Lookup `binding` and `sig` for matches in all modules of the docsystem. diff --git a/test/docs.jl b/test/docs.jl index 6cf639c5d6ad8..56aaf44b6be01 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -930,7 +930,7 @@ type DynamicDocType x end -Base.Docs.getdoc(d::DynamicDocType) = d.x +Base.Docs.getdoc(d::DynamicDocType) = Base.Markdown.parse(d.x) dynamic_test = DynamicDocType("test 1") @test docstrings_equal(@doc(dynamic_test), doc"test 1")