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.

I don't think you can do that yet. See for example: https://github.com/JuliaLang/julia/issues/3988 — ivarne, Nov 06 '13 at 20:23
This will be happening soon. See discussion [here](https://github.com/JuliaLang/julia/issues/8514) — spencerlyon2, Oct 07 '14 at 12:17

score 60 · Accepted Answer · edited Feb 05 '19 at 15:55

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.

score 34 · Answer 2 · edited Nov 22 '19 at 15:56

34

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.

edited Nov 22 '19 at 15:56

logankilpatrick

13,148
7
44
125

answered Feb 17 '17 at 06:10

Harrison Grodin

2,253
2
19
30

This doesn't seem to work in Julia 1.7: I type `"""My function"""` - and this gets evaluated as the string `"My function\n"`, so I don't get a chance to input the actual function definition... – ForceBru Nov 20 '21 at 17:34
In the REPL, press - (or – Harrison Grodin Nov 21 '21 at 18:24
does not work in my Windows REPL: it turns the REPL full-screen instead. (That's a cmd feature.) – Fred vdP Dec 13 '21 at 14:56

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

2 Answers2

Linked