Merge pull request #13017 from MichaelHatherly/mh/doc-syntax

Document all documentable syntax

doc/manual/documentation.rst

@@ -123,6 +123,198 @@ Or for use with Julia's metaprogramming functionality:
     @doc "`add(a,b)` adds `a` and `b` together" add
     @doc "`subtract(a,b)` subtracts `b` from `a`" subtract
 
+Syntax Guide
+------------
+
+A comprehensive overview of all documentable Julia syntax.
+
+In the following examples ``"..."`` is used to illustrate an arbitrary docstring which may
+be one of the follow four variants and contain arbitrary text:
+
+.. code-block:: julia
+
+    "..."
+
+    doc"..."
+
+    """
+    ...
+    """
+
+    doc"""
+    ...
+    """
+
+``@doc_str`` should only be used when the docstring contains ``$`` or ``\`` characters that
+should not be parsed by Julia such as LaTeX syntax or Julia source code examples containing
+interpolation.
+
+Functions and Methods
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: julia
+
+    "..."
+    function f end
+
+    "..."
+    f
+
+Adds docstring ``"..."`` to ``Function`` ``f``. The first version is the preferred syntax,
+however both are equivalent.
+
+.. code-block:: julia
+
+    "..."
+    f(x) = x
+
+    "..."
+    function f(x)
+        x
+    end
+
+    "..."
+    f(x)
+
+Adds docstring ``"..."`` to ``Method`` ``f(::Any)``.
+
+.. code-block:: julia
+
+    "..."
+    f(x, y = 1) = x + y
+
+Adds docstring ``"..."`` to two ``Method``\ s, namely ``f(::Any)`` and ``f(::Any, ::Any)``.
+
+Types
+~~~~~
+
+.. code-block:: julia
+
+    "..."
+    abstract T
+
+    "..."
+    type T end
+
+    "..."
+    immutable T end
+
+Adds the docstring ``"..."`` to type ``T``.
+
+.. code-block:: julia
+
+    "..."
+    type T
+        "x"
+        x
+        "y"
+        y
+    end
+
+Adds docstring ``"..."`` to type ``T``, ``"x"`` to field ``T.x`` and ``"y"`` to field
+``T.y``. Also applicable to ``immutable`` types.
+
+.. code-block:: julia
+
+    "..."
+    typealias A T
+
+Adds docstring ``"..."`` to the ``Binding`` ``A``.
+
+``Binding``\ s are used to store a reference to a particular ``Symbol`` in a ``Module``
+without storing the referenced value itself.
+
+Macros
+~~~~~~
+
+.. code-block:: julia
+
+    "..."
+    macro m() end
+
+    "..."
+    :(@m)
+
+Adds docstring ``"..."`` to the ``Binding`` ``@m``. Adding documentation at the definition
+is the preferred approach.
+
+Modules
+~~~~~~~
+
+.. code-block:: julia
+
+    "..."
+    module M end
+
+    module M
+
+    "..."
+    M
+
+    end
+
+Adds docstring ``"..."`` to the ``Module`` ``M``. Adding the docstring above the ``Module``
+is the preferred syntax, however both are equivalent.
+
+Global Variables
+~~~~~~~~~~~~~~~~
+
+.. code-block:: julia
+
+    "..."
+    const a = 1
+
+    "..."
+    b = 2
+
+    "..."
+    global c = 3
+
+Adds docstring ``"..."`` to the ``Binding``\ s ``a``, ``b``, and ``c``.
+
+.. code-block:: julia
+
+    "..."
+    sym
+
+Adds docstring ``"..."`` to the value associated with ``sym``. Users should prefer
+documenting ``sym`` at it's definition.
+
+Multiple Objects
+~~~~~~~~~~~~~~~~
+
+.. code-block:: julia
+
+    "..."
+    a, b
+
+Adds docstring ``"..."`` to ``a`` and ``b`` each of which should be a documentable
+expression. This syntax is equivalent to
+
+.. code-block:: julia
+
+    "..."
+    a
+
+    "..."
+    b
+
+Any number of expressions many be documented together in this way. This syntax can be useful
+when two functions are related, such as non-mutating and mutating versions ``f`` and ``f!``.
+
+Macro-generated code
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: julia
+
+    "..."
+    @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.
+
 Markdown Syntax Notes
 ---------------------