Come rendere disponibili a julia REPL le descrizioni delle funzioni definite dall'utente ("docstrings")?

In che modo le funzioni definite dall'utente (ad esempio f) possono avere stampe significative quando vengono ispezionate tramite REPL utilizzando ?fohelp(f)

Ad esempio, immagina di scrivere la seguente funzione

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

Se lo carico in una sessione julia e provo, help(f)ottengo quanto segue:

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

E se invece volessi vedere qualcosa di simile

julia> help(f)
f

   Compute 2 times x minus y squared

dove la descrizione "Calcola 2 volte x meno y al quadrato" è scritta da qualche parte. Immagino che la risposta alla mia domanda possa essere determinata dalla risposta alla domanda "Dov'è da qualche parte la descrizione dovrebbe essere scritta?"

A titolo di esempio, se volessi fare lo stesso in python, potrei definire la funzione e inserire la descrizione come docstring:

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

che renderebbe la mia descrizione immediatamente disponibile quando digito help(f)o f?da IPython.

È possibile utilizzare la @docmacro nelle versioni di Julia 0.4 (ottobre 2015) e successive.

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

Modifica: come sottolineato da @Harrison Grodin, le versioni 0.5 e successive supportano una sintassi abbreviata così come Markdown, LaTEX e alcune altre chicche:

"""
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

Ci sono maggiori dettagli nella documentazione .

In Julia v0.5 + ( comprese le versioni Julia più recenti come 1.2+ ), puoi scrivere una stringa multilinea sopra la definizione della funzione. (Non ce @docn'è più bisogno .)

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

Per ulteriori informazioni sulla formattazione corretta delle stringhe di documentazione, vedere la documentazione ufficiale di Julia .