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

¿Cómo pueden las funciones definidas por el usuario (por ejemplo f) tener impresiones significativas cuando se inspeccionan a través del REPL utilizando ?fo help(f)

Por ejemplo imagine que escribo la siguiente funciton

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

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

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

Y si en lugar de eso quisiera ver algo como{[11]]} 

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 alguna parte. Supongo que la respuesta a mi pregunta puede ser determinado 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 docstring: 

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 inmediatamente cuando escriba help(f) o f? desde IPython.

 76
julia-lang
Author: spencerlyon2, 2013-11-06
Source

2 answers

Puede utilizar el @doc macro en las versiones de Julia 0.4 (Oct. 2015) y superiores. 

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

 46
Author: Allen Luce,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-08-09 22:09:46

En Julia v0.5+, puede escribir una cadena multilínea sobre la definición de la función. (Ya no hay necesidad de @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 las cadenas de documentos, consulte la documentación oficial de Julia.

 11
Author: Harrison Grodin,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-02-17 06:10:30