Merge pull request #133 from JuliaDocs/mh/capture-expr

Support capturing `Expr` for use in abbreviations.

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,23 @@
+module InterpolationTestModule
+
+struct TestType
+    value::Int
+end
+
+import DocStringExtensions
+
+# For TestType(1), it interpolates the function signature, and for
+# TestType(2) it interpolates the function body.
+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[]