From 443f30dc498bf5c80a9ea06a10f7c3074dd6d33f Mon Sep 17 00:00:00 2001
From: Milan Bouchet-Valat <nalimilan@club.fr>
Date: Mon, 19 Dec 2016 12:40:03 +0100
Subject: [PATCH] Add signatures to docstring examples in the manual

These examples did not follow the guidelines given in the rest
of the page. Also mark a few code blocks as being Julia code.
---
 doc/src/manual/documentation.md | 38 ++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/doc/src/manual/documentation.md b/doc/src/manual/documentation.md
index 1c77ba0e3b4d5..46f1397461a5d 100644
--- a/doc/src/manual/documentation.md
+++ b/doc/src/manual/documentation.md
@@ -11,7 +11,7 @@ The basic syntax is very simple: any string appearing at the top-level right bef
 (function, macro, type or instance) will be interpreted as documenting it (these are called *docstrings*).
 Here is a very simple example:
 
-```
+```julia
 "Tell whether there are too foo items in the array."
 foo(xs::Array) = ...
 ```
@@ -138,7 +138,7 @@ As in the example above, we recommend following some simple conventions when wri
 
    That is, write:
 
-   ```
+   ```julia
    """
    ...
 
@@ -149,7 +149,7 @@ As in the example above, we recommend following some simple conventions when wri
 
    rather than:
 
-   ```
+   ```julia
    """...
 
    ..."""
@@ -185,25 +185,37 @@ itself (i.e. the object created without any methods by `function bar end`). Spec
 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:
 
-```
+```julia
 """
+    *(x, y, z...)
+
 Multiplication operator. `x*y*z*...` calls this function with multiple
 arguments, i.e. `*(x,y,z...)`.
 """
-function *(x, y)
-  # ... [implementation sold separately] ...
+function *(x, y, z...)
+    # ... [implementation sold separately] ...
 end
 
-"When applied to strings, concatenates them."
-function *(x::AbstractString, y::AbstractString)
-  # ... [insert secret sauce here] ...
+"""
+    *(x::AbstractString, y::AbstractString, z::AbstractString...)
+
+When applied to strings, concatenates them.
+"""
+function *(x::AbstractString, y::AbstractString, z::AbstractString...)
+    # ... [insert secret sauce here] ...
 end
 
-help?>*
-Multiplication operator. `x*y*z*...` calls this function with multiple
-arguments, i.e. `*(x,y,z...)`.
+help?> *
+search: * .*
 
-When applied to strings, concatenates them.
+  *(x, y, z...)
+
+  Multiplication operator. x*y*z*... calls this function with multiple
+  arguments, i.e. *(x,y,z...).
+
+  *(x::AbstractString, y::AbstractString, z::AbstractString...)
+
+  When applied to strings, concatenates them.
 ```
 
 When retrieving documentation for a generic function, the metadata for each method is concatenated