How to make user defined function descriptions (“docstrings”) available to julia REPL?

Question

How can user defined functions (say f) have meaningful printouts when inspected via the REPL using ?for help(f)

For example imagine I write the following funciton

function f(x::Float64, y::Float64)
    return 2x - y^2
end

If I load this into a julia session and try help(f) I get the following:

julia> help(f)
f (generic function with 1 method)

What if instead I wanted to see something like

julia> help(f)
f

   Compute 2 times x minus y squared

where the description "Compute 2 times x minus y squared" is written somewhere. I am guessing the answer to my question can be determined from the answer to the question "Where is the somewhere the description should be written?"

---

By way of example, if I wanted to do the same in python, I could define the function and put the description as a docstring:

def f(x, y):
    """
    Compute 2 times x minus y squared
    """
    return 2 *  x - y ** 2

which would make my description immediately available when I type help(f) or f? from IPython.

Answer 1

You can use the @doc macro in Julia versions 0.4 (Oct. 2015) and above.

% julia
               _
   _       _ _(_)_     |  A fresh approach to technical computing
  (_)     | (_) (_)    |  Documentation: http://docs.julialang.org
   _ _   _| |_  __ _   |  Type "?help" for help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 0.4.0 (2015-10-08 06:20 UTC)
 _/ |\__'_|_|_|\__'_|  |  Official http://julialang.org/ release
|__/                   |  x86_64-apple-darwin13.4.0

julia> @doc """
       Compute 2 times x minus y squared.
       """ ->
       function f(x::Float64, y::Float64)
           return 2x - y^2
       end
f (generic function with 1 method)

julia> @doc f
  Compute 2 times x minus y squared.

Edit: As pointed out by @Harrison Grodin, versions 0.5 and above support an abbreviated syntax as well as Markdown, LaTEX, and a few other goodies:

"""
Calculate the left Riemann sum[^1] approximating ``\int_a^b f(x) dx = F(b) - F(a).``

[^1]: Thomas G., Finney R. (1996), Calculus and Analytic Geometry, Addison Wesley, ISBN 0-201-53174-7
"""
function rs(a, b, d, f)
end

There are more details in the documentation.

Answer 2

In Julia v0.5+ (including more recent Julia Versions like 1.2+), you can write a multiline string above the function definition. (No need for @doc anymore.)

julia> """
           cube(x)

       Compute the cube of `x`, ``x^3``.

       # Examples
       ```jldoctest
       julia> cube(2)
       8
       ```
       """
       function cube(x)
           x^3
       end
cube

help?> cube
search: Cdouble isexecutable Ac_mul_B Ac_mul_Bc Ac_mul_B! Ac_mul_Bc! cumsum_kbn

  cube(x)

  Compute the cube of x, x^3.

     Examples
    ≡≡≡≡≡≡≡≡≡≡

  julia> cube(2)
  8

For more information on properly formatting your docstrings, see the official Julia Documentation.