From 1023b8552548c3884644cff7f47d810eae00474b Mon Sep 17 00:00:00 2001 From: Michael Hatherly Date: Tue, 29 Sep 2015 14:14:33 +0200 Subject: [PATCH] Update documenting macro-generated code docs [skip ci] --- doc/manual/documentation.rst | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/doc/manual/documentation.rst b/doc/manual/documentation.rst index 08d9b4ecea7be..864d2479825a4 100644 --- a/doc/manual/documentation.rst +++ b/doc/manual/documentation.rst @@ -351,10 +351,35 @@ Macro-generated code "..." @m expression -Adds docstring ``"..."`` to expression generated by expanding ``@m expression``. This syntax -is only valid if expanding ``@m`` results in a single expression that can be documented. -This allows for functions decorated with ``@inline``, ``@noinline``, and ``@generated`` to -be documented in the same way as other functions. +Adds docstring ``"..."`` to expression generated by expanding ``@m expression``. This allows +for expressions decorated with ``@inline``, ``@noinline``, ``@generated``, or any other +macro to be documented in the same way as undecorated expressions. + +Macro authors should take note that only macros that generate a `single expression` will +automatically support docstrings. If a macro returns a block containing multiple +subexpressions then the subexpression that should be documented must be marked using the +:func:`@__doc__` macro. + +The ``@enum`` macro makes use of ``@__doc__`` to allow for documenting ``Enum``\ s. +Examining it's definition should serve as an example of how to use ``@__doc__`` correctly. + +.. function:: @__doc__(ex) + + .. Docstring generated from Julia source + + Low-level macro used to mark expressions returned by a macro that should be documented. If more than one expression is marked then the same docstring is applied to each expression. + + .. code-block:: julia + + macro example(f) + quote + $(f)() = 0 + @__doc__ $(f)(x) = 1 + $(f)(x, y) = 2 + end |> esc + end + + ``@__doc__`` has no effect when a macro that uses it is not documented. Markdown Syntax Notes ---------------------