Documentation¶

Julia enables package developers and users to document functions, types and other objects easily via a built-in documentation system since Julia 0.4.

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:

"Tell whether there are too foo items in the array."foo(xs::Array)=...

Documentation is interpreted as 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:

"""    bar(x[, y])Compute the Bar index between `x` and `y`. If `y` is missing, computethe Bar index between all pairs of columns of `x`.# Examples```juliajulia> bar([1, 2], [1, 2])1```"""function bar(x,y)...

As in the example above, we recommend following some simple conventions when writing documentation:

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 a simplified form. Optional arguments should be represented with their default values (i.e. f(x,y=1)) when possible, following the actual Julia syntax. Optional arguments which do not have a default value should be put in brackets (i.e. f(x[,y]) and f(x[,y[,z]])). 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. When a function accepts many keyword arguments, only include a <keywordarguments> placeholder in the signature (i.e. f(x;<keywordarguments>)), and give the complete list under an #Arguments section (see point 4 below).

2. Include a single one-line sentence describing what the function does or what the object represents after the simplified signature block. If needed, provide more details in a second paragraph, after a blank line.

   The one-line sentence should use the imperative form (“Do this”, “Return that”) instead of the third person (do not write “Returns the length...”) when documenting functions. It should end with a period. If the meaning of a function cannot be summarized easily, splitting it into separate composable parts could be beneficial (this should not be taken as an absolute requirement for every single case though).

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

4. 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, providing an argument list can be a good idea for complex functions with many arguments (in particular keyword arguments). In that case, insert it after the general description of the function, under an #Arguments header, with one * bullet for each argument. The list should mention the types and default values (if any) of the arguments:

   """...# Arguments* `n::Integer`: the number of elements to compute.* `dim::Integer=1`: the dimensions along which to perform the computation...."""

5. Include any code examples in an #Examples section.

   Examples should, whenever possible, be written as doctests. A doctest is a fenced code block (see Code blocks) starting with ```jldoctest and contains any number of julia> prompts together with inputs and expected outputs that mimic the Julia REPL.

   For example in the following docstring a variable a is defined and the expected result, as printed in a Julia REPL, appears afterwards:

   """Some nice documentation here.# Examples```jldoctestjulia> a = [1 2; 3 4]2×2 Array{Int64,2}: 1  2 3  4```"""

   Warning

   Calling rand and other RNG-related functions should be avoided in doctests since they will not produce consistent outputs during different Julia sessions.

   Operating system word size (Int32 or Int64) as well as path separator differences (/ or \) will also effect the reproducibility of some doctests.

   Note that whitespace in your doctest is significant! The doctest will fail if you misalign the output of pretty-printing an array, for example.

   You can then run make-Cdocdoctest to run all the doctests in the Julia Manual, which will ensure that your example works.

   Examples that are untestable should be written within fenced code blocks starting with ```julia so that they are highlighted correctly in the generated documentation.

   Tip

   Wherever possible examples should be self-contained and runnable so that readers are able to try them out without having to include any dependencies.

6. Use backticks to identify code and equations.

   Julia identifiers and code excerpts should always appear between backticks ` to enable highlighting. Equations in the LaTeX syntax can be inserted between double backticks ``. Use Unicode characters rather than their LaTeX escape sequence, i.e. ``α=1`` rather than ``\\alpha=1``.

7. Place the starting and ending """ characters on lines by themselves.

   That is, write:

   """......"""f(x,y)=...

   rather than:

   """......"""f(x,y)=...

   This makes it more clear where docstrings start and end.

8. Respect the line length limit used in the surrounding code.

   Docstrings are edited using the same tools as code. Therefore, the same conventions should apply. It it advised to add line breaks after 92 characters.

?fft?@time?r""

"""Multiplication operator. `x*y*z*...` calls this function with multiplearguments, i.e. `*(x,y,z...)`."""function*(x,y)# ... [implementation sold separately] ...end"When applied to strings, concatenates them."function*(x::AbstractString,y::AbstractString)# ... [insert secret sauce here] ...endhelp?>*Multiplicationoperator.`x*y*z*...`callsthisfunction withmultiplearguments,i.e.`*(x,y,z...)`.Whenappliedtostrings,concatenatesthem.

@doc"..."foo!@doc(@docfoo!)foo

for(f,op)in((:add,:+),(:subtract,:-),(:multiply,:*),(:divide,:/))@evalbegin$f(a,b)=$op(a,b)endend@doc"`add(a,b)` adds `a` and `b` together"add@doc"`subtract(a,b)` subtracts `b` from `a`"subtract

ifVERSION>v"0.4""..."f(x)=xend

ifVERSION>v"0.4"@doc"..."->f(x)=xend

"..."doc"...""""..."""doc"""..."""

"..."function fend"..."f

"..."f(x)=x"..."function f(x)xend"..."f(x)

"..."f(x,y=1)=x+y

"..."macrom(x)end

"...":(@m)

"..."abstract T1"..."type T2...end"..."immutableT3...end

"..."type T"x"x"y"yend

"..."typealias AT

"..."moduleMendmoduleM"..."Mend

"..."baremoduleM# ...endbaremoduleMimportBase:@doc"..."f(x)=xend

"..."consta=1"..."b=2"..."globalc=3

"..."f(x)=x+1constalias=f

f(x)=x+1"..."constalias=f

"..."sym

"..."a,b

"..."a"..."b

"..."@mexpression

A paragraph containing a **bold** word.

A paragraph containing an *emphasised* word.

A paragraph containing a `literal` word.

A paragraph containing a ``` `backtick` character ```.

A paragraph containing some ``\LaTeX`` markup.

A paragraph containing a link to [Julia](http://www.julialang.org).

A paragraph containing a numbered footnote [^1] and a named one [^named].

This is a paragraph.

And this is *another* one containing some emphasised text.
A new line, but still part of the same paragraph.

# Level One
## Level Two
### Level Three
#### Level Four
##### Level Five
###### Level Six

This is a paragraph.

    function func(x)
        # ...
    end

Another paragraph.

A code block without a "language":

```
function func(x)
    # ...
end
```

and another one with the "language" specified as `julia`:

```julia
function func(x)
    # ...
end
```

Here's a quote:

> Julia is a high-level, high-performance dynamic programming language for
> technical computing, with syntax that is familiar to users of other
> technical computing environments.

![alternative text](link/to/image.png)

A list of items:

  * item one
  * item two
  * item three

Another list:

  * item one

  * item two

    ```
    f(x) = x
    ```

  * And a sublist:

      + sub-item one
      + sub-item two

Two ordered lists:

 1. item one
 2. item two
 3. item three


 5) item five
 6) item six
 7) item seven

```math
f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta
```

[^1]: Numbered footnote text.

[^note]:

    Named footnote text containing several toplevel elements.

      * item one
      * item two
      * item three

    ```julia
    function func(x)
        # ...
    end
    ```

Text above the line.

---

And text below the line.

| Column One | Column Two | Column Three |
|:---------- | ---------- |:------------:|
| Row `1`    | Column `2` |              |
| *Row* 2    | **Row** 2  | Column ``3`` |

!!! note

    This is the content of the note.

!!! warning "Beware!"

    And this is another one.

    This warning admonition has a custom title: `"Beware!"`.