Update documenting macro-generated code docs

[skip ci]

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
 ---------------------