Como tornar descrições de funções definidas pelo usuário (“docstrings”) disponíveis para julia REPL?

Como as funções definidas pelo usuário (digamos f) podem ter impressões significativas quando inspecionadas através do REPL usando ?fouhelp(f)

Por exemplo, imagine que eu escrevo a seguinte função

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

Se eu carregar isso em uma sessão julia e tentar help(f), obtenho o seguinte:

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

E se eu quisesse ver algo como

julia> help(f)
f

   Compute 2 times x minus y squared

onde a descrição "Calcule 2 vezes x menos y ao quadrado" está escrita em algum lugar. Estou supondo que a resposta à minha pergunta pode ser determinada a partir da resposta à pergunta "Onde fica o lugar em que a descrição deve ser escrita?"

A título de exemplo, se eu quisesse fazer o mesmo em python, poderia definir a função e colocar a descrição como uma docstring:

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

o que tornaria minha descrição imediatamente disponível quando eu digitar help(f)ou f?do IPython.

Você pode usar a @docmacro nas versões Julia 0.4 (outubro de 2015) e acima.

% 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: Como apontado por @Harrison Grodin, as versões 0.5 e acima suportam uma sintaxe abreviada, bem como Markdown, LaTEX e alguns outros 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

Existem mais detalhes na documentação .

No Julia v0.5 + ( incluindo versões Julia mais recentes como 1.2+ ), você pode escrever uma string multilinha acima da definição da função. (Não há necessidade de @docmais.)

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

Para obter mais informações sobre a formatação adequada de suas docstrings, consulte a documentação oficial da Julia .