¿Cómo hacer que las descripciones de funciones definidas por el usuario ("cadenas de documentos") estén disponibles para julia REPL?

¿Cómo pueden las funciones definidas por el usuario (digamos f) tener impresiones significativas cuando se inspeccionan a través del REPL usando ?fohelp(f)

Por ejemplo, imagina que escribo la siguiente función

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

Si cargo esto en una sesión de julia y lo intento help(f), obtengo lo siguiente:

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

¿Y si en cambio quisiera ver algo como

julia> help(f)
f

   Compute 2 times x minus y squared

donde la descripción "Calcular 2 veces x menos y al cuadrado" está escrita en algún lugar. Supongo que la respuesta a mi pregunta se puede determinar a partir de la respuesta a la pregunta "¿Dónde está el lugar donde se debe escribir la descripción?"

A modo de ejemplo, si quisiera hacer lo mismo en Python, podría definir la función y poner la descripción como una cadena de documentos:

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

lo que haría que mi descripción estuviera disponible de inmediato cuando escribo help(f)o f?desde IPython.

Puede utilizar la @docmacro en las versiones de Julia 0.4 (octubre de 2015) y posteriores.

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

Editar: Como lo señaló @Harrison Grodin, las versiones 0.5 y superiores admiten una sintaxis abreviada, así como Markdown, LaTEX y algunas otras ventajas:

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

Hay más detalles en la documentación .

En Julia v0.5 + ( incluidas las versiones de Julia más recientes como 1.2+ ), puede escribir una cadena de varias líneas encima de la definición de la función. (Ya no es necesario @doc).

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 obtener más información sobre cómo formatear correctamente sus cadenas de documentos, consulte la documentación oficial de Julia .