CODEWITHSUNDEEP
julia
spencerlyon2
spencerlyon2

Reputation: 9676

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

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.

Upvotes: 101

Views: 13182

Answers (2)

Harrison Grodin
Harrison Grodin

Reputation: 2313

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.

Upvotes: 34

Allen Luce
Allen Luce

Reputation: 8389

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.

Upvotes: 61

Related Questions