Add the FUNCTIONNAME abbreviation. (#66)

Fixes #59.

Author: tpapp

src/DocStringExtensions.jl

@@ -77,8 +77,7 @@ module DocStringExtensions
 
 # Exports.
 
-export @template, FIELDS, EXPORTS, METHODLIST, IMPORTS, SIGNATURES, TYPEDEF, DOCSTRING
-
+export @template, FIELDS, EXPORTS, METHODLIST, IMPORTS, SIGNATURES, TYPEDEF, DOCSTRING, FUNCTIONNAME
 
 # Includes.
 

src/abbreviations.jl

@@ -303,6 +303,46 @@ function format(::MethodSignatures, buf, doc)
     end
 end
 
+#
+# `FunctionName`
+#
+
+"""
+The singleton type for [`FUNCTIONNAME`](@ref) abbreviations.
+
+$(:FIELDS)
+"""
+struct FunctionName <: Abbreviation end
+
+"""
+An [`Abbreviation`](@ref) for including the function name matching the method of
+the docstring.
+
+# Usage
+
+This is mostly useful for not repeating the function name in docstrings where
+the user wants to retain full control of the argument list, or the latter does
+not exist (eg generic functions).
+
+Note that the generated docstring snippet is not quoted, use indentation or
+explicit quoting.
+
+# Example
+
+```julia
+\"""
+    \$(FUNCTIONNAME)(d, θ)
+
+Calculate the logdensity `d` at `θ`.
+
+Users should define their own methods for `$(FUNCTIONNAME)`.
+\"""
+function logdensity end
+```
+"""
+const FUNCTIONNAME = FunctionName()
+
+format(::FunctionName, buf, doc) = print(buf, doc.data[:binding].var)
 
 #
 # `TypeSignature`

test/tests.jl

@@ -182,6 +182,17 @@ end
             @test occursin("\n```\n", str)
         end
 
+        @testset "function names" begin
+            doc.data = Dict(
+                :binding => Docs.Binding(M, :f),
+                :typesig => Tuple{Any},
+                :module => M,
+            )
+            DSE.format(FUNCTIONNAME, buf, doc)
+            str = String(take!(buf))
+            @test str == "f"
+        end
+
         @testset "type definitions" begin
             doc.data = Dict(
                 :binding => Docs.Binding(M, :AbstractType),