Add guidelines for writing inline docstrings to the manual

[av skip]

doc/manual/documentation.rst

@@ -5,11 +5,17 @@
 ***************
 
 Julia enables package developers and users to document functions, types and
-other objects easily, either via the built-in documentation system in Julia 0.4
-or the `Docile.jl <https://github.com/MichaelHatherly/Docile.jl>`_ package in
-Julia 0.3.
+other objects easily via a built-in documentation system since Julia 0.4.
 
-In 0.4:
+.. tip::
+
+    This documentation system can also be used in Julia 0.3 via the
+    `Docile.jl <https://github.com/MichaelHatherly/Docile.jl>`_ package; see
+    the documentation for that package for more details.
+
+The basic syntax is very simple: any string appearing at the top-level right
+before an object (function, macro, type or instance) will be interpreted as
+documenting it (these are called *docstrings*). Here is a very simple example:
 
 .. doctest::
 
@@ -18,25 +24,67 @@ In 0.4:
 
 Documentation is interpreted as `Markdown <https://en.wikipedia.org/wiki/Markdown>`_,
 so you can use indentation and code fences to delimit code examples from text.
+Technically, any object can be associated with any other as metadata;
+Markdown happens to be the default, but one can construct other string
+macros and pass them to the ``@doc`` macro just as well.
+
+Here is a more complex example, still using Markdown:
 
 .. doctest::
 
     """
-    The `@bar` macro will probably make your code 2x faster or something. Use
-    it like this:
+        bar(x[, y])
+
+    Computes the Bar index between `x` and `y`. If `y` is missing, the function computes
+    the index between all pairs of columns of `x`.
 
-        @bar buy_drink_for("Jiahao")
+    # Examples
+    ```jldoctest
+    julia> bar([1, 2], [1, 2])
+    1
+    ```
     """
-    macro bar(ex) ...
+    function bar(x, y) ...
 
-Documentation is very free-form; there are no set formatting
-restrictions or strict conventions. It's hoped that best practices will
-emerge fairly naturally as package developers learn to use the new
-system.
+Documentation is very free-form, though we recommend following some simple
+conventions, illustrated in the above example.
 
-Technically, any object can be associated with any other as metadata;
-Markdown happens to be the default, but one can construct other string
-macros and pass them to the ``@doc`` macro just as well.
+1. Always show the signature of a function at the top of the documentation,
+with a four-space indent so that it is printed as Julia code.
+
+  This can be identical to the signature present in the Julia code
+  (like ``mean(x::AbstractArray)``), or use a simplified form.
+  Optional arguments should be put into brackets ``[]``, with their default values
+  when applicable. An alternative solution is to use several lines: one without
+  optional arguments, the other(s) with them. This solution can also be used to
+  document several related methods of a given function.
+
+2. Do not repeat yourself.
+
+  Since the function name is given by the signature, there is no need to
+  start the documentation with "The function ``bar``...": go straight to the point.
+  Similarly, if the signature specifies the types of the arguments, mentioning them
+  in the description is redundant.
+
+3. Only provide an argument list when really necessary.
+
+  For simple functions, it is often clearer
+  to mention the role of the arguments directly in the description of the function's
+  purpose. An argument list would only repeat information already provided elsewhere.
+  However, it it might be a good idea for complex functions with many arguments. In
+  that case, put the argument list after the general description of the function, under
+  a ``# Arguments`` header, with one ``*`` bullet for each argument.
+
+4. When adding examples, use ``jldoctest`` blocks instead of standard text.
+
+  This allows running examples automatically and checking that their actual output is
+  consistent with that presented in the documentation. This way, the code is tested and
+  examples cannot get out of date without notice. Examples should be grouped under an
+  ``# Examples`` section.
+
+5. Always put Julia identifiers and code excerpts between backticks `````.
+
+  This enables automatic highlighting.
 
 Accessing Documentation
 -----------------------
@@ -60,8 +108,12 @@ Functions & Methods
 
 Functions in Julia may have multiple implementations, known as methods.
 While it's good practice for generic functions to have a single purpose,
-Julia allows methods to be documented individually if necessary. For
-example:
+Julia allows methods to be documented individually if necessary.
+In general, only the most generic method should be documented, or even the
+function itself (i.e. the object created without any methods by
+``function bar end``). Specific methods should only be documented if their
+behaviour differs from the more generic ones. In any case, they should not
+repeat the information provided elsewhere. For example:
 
 .. doctest::