Support capturing Expr for use in abbreviations.

Add a generic interface function `interpolation` that hooks into the
stage after macro expansion so that interpolated values in docstrings
can implement their own behaviour rather than being directly
interpolated into the docstring. Pass the documented expression through
to `interpolation` such that abbreviation implementations can make use
of this expression for their own needs.

Author: MichaelHatherly

src/DocStringExtensions.jl

@@ -82,6 +82,7 @@ import LibGit2
 export @template, FIELDS, TYPEDFIELDS, EXPORTS, METHODLIST, IMPORTS
 export SIGNATURES, TYPEDSIGNATURES, TYPEDEF, DOCSTRING, FUNCTIONNAME
 export README, LICENSE
+export interpolation
 
 # Includes.
 

src/templates.jl

@@ -97,6 +97,7 @@ end
 # On v0.6 and below it seems it was assumed to be (docstr::String, expr::Expr), but on v0.7
 # it is (source::LineNumberNode, mod::Module, docstr::String, expr::Expr)
 function template_hook(source::LineNumberNode, mod::Module, docstr, expr::Expr)
+    docstr = _capture_expression(docstr, expr)
     # During macro expansion we only need to wrap docstrings in special
     # abbreviations that later print out what was before and after the
     # docstring in it's specific template. This is only done when the module

src/utilities.jl

@@ -3,6 +3,42 @@
 # Utilities.
 #
 
+#
+# Expression Capture.
+#
+
+"""
+    interpolation(object::T, captured::Expr) -> new_object
+
+Interface method for hooking into interpolation within docstrings to change
+the behaviour of the interpolation. `object` is the interpolated object within a
+docstring and `captured` is the raw expression that is documented by the docstring
+in which the interpolated `object` has been included.
+
+To define custom behaviour for your own `object` types implement a method of
+`interpolation(::T, captured)` for type `T` and return a `new_object` to
+be interpolated into the final docstring. Note that you must own the definition
+of type `T`. `new_object` does not need to be of type `T`.
+"""
+interpolation(@nospecialize(object), @nospecialize(_)) = object
+
+# During macro expansion process the interpolated string and replace all interpolation
+# syntax with calls to `interpolation` that pass through the documented expression along
+# with the resolved object that was interpolated.
+function _capture_expression(docstr::Expr, expr::Expr)
+    if Meta.isexpr(docstr, :string)
+        quoted = QuoteNode(expr)
+        new_docstring = Expr(:string)
+        append!(new_docstring.args, [_process_interpolation(each, quoted) for each in docstr.args])
+        return new_docstring
+    end
+    return docstr
+end
+_capture_expression(@nospecialize(other), ::Expr) = other
+
+_process_interpolation(str::AbstractString, ::QuoteNode) = str
+_process_interpolation(@nospecialize(expr), quoted::QuoteNode) = Expr(:call, interpolation, expr, quoted)
+
 #
 # Method grouping.
 #

test/interpolation.jl

@@ -0,0 +1,21 @@
+module InterpolationTestModule
+
+struct TestType
+    value::Int
+end
+
+import DocStringExtensions
+
+DocStringExtensions.interpolation(obj::TestType, ex::Expr) = ex.args[obj.value]
+
+"""
+$(TestType(1))
+"""
+f(x) = x + 1
+
+"""
+$(TestType(2))
+"""
+g(x) = x + 2
+
+end

test/tests.jl

@@ -1,6 +1,7 @@
 const DSE = DocStringExtensions
 
 include("templates.jl")
+include("interpolation.jl")
 include("TestModule/M.jl")
 
 # initialize a test repo in test/TestModule which is needed for some tests
@@ -516,6 +517,12 @@ end
             @test fmt(:(TemplateTests.OtherModule.f)) == "method `f`\n"
         end
     end
+    @testset "Interpolation" begin
+        let fmt = expr -> Markdown.plain(eval(:(@doc $expr)))
+            @test occursin("f(x)", fmt(:(InterpolationTestModule.f)))
+            @test occursin("x + 2", fmt(:(InterpolationTestModule.g)))
+        end
+    end
     @testset "utilities" begin
         @testset "keywords" begin
             @test DSE.keywords(M.T, first(methods(M.T))) == Symbol[]