web-dev-qa-db-fra.com

Comment mettre à la disposition de Julia REPL des descriptions de fonctions définies par l'utilisateur ("docstrings")?

Comment les fonctions définies par l'utilisateur (par exemple f) peuvent-elles avoir des impressions significatives lorsqu'elles sont inspectées via le REPL en utilisant ?f Ou help(f)

Par exemple, imaginez que j'écris la fonction suivante

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

Si je charge ceci dans une session Julia et essaie help(f) j'obtiens ce qui suit:

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

Et si à la place je voulais voir quelque chose comme

Julia> help(f)
f

   Compute 2 times x minus y squared

où la description "Calculer 2 fois x moins y au carré" est écrite quelque part. Je suppose que la réponse à ma question peut être déterminée à partir de la réponse à la question "Où est le lieu où la description doit être écrite?"

À titre d'exemple, si je voulais faire de même en python, je pourrais définir la fonction et mettre la description en tant que docstring:

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

ce qui rendrait ma description immédiatement disponible lorsque je tape help(f) ou f? depuis IPython.

julia
86
spencerlyon2

Vous pouvez utiliser le @doc macro dans les versions 0.4 de Julia (octobre 2015) et supérieures.

% 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: Comme souligné par @Harrison Grodin, les versions 0.5 et supérieures prennent en charge une syntaxe abrégée ainsi que Markdown, LaTEX et quelques autres 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

Il y a plus de détails dans la documentation .

52
Allen Luce

Dans Julia v0.5 + ( y compris les versions Julia plus récentes comme 1.2 + ), vous pouvez écrire une chaîne multiligne au-dessus de la définition de la fonction. (Pas besoin d @doc plus.)

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

Pour plus d'informations sur la mise en forme correcte de vos docstrings, consultez la documentation officielle Julia Documentation .

24
Harrison Grodin