Frage Wie kann julia REPL benutzerdefinierte Funktionsbeschreibungen ("Docstrings") zur Verfügung stellen?


Wie können benutzerdefinierte Funktionen (z. B. f) haben aussagekräftige Ausdrucke bei der Überprüfung über die REPL mit ?foder help(f)

Stellen Sie sich zum Beispiel vor, ich schreibe die folgende Funktion

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

Wenn ich das in eine julia-Sitzung lade und versuche help(f) Ich bekomme Folgendes:

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

Was wenn ich stattdessen etwas sehen wollte

julia> help(f)
f

   Compute 2 times x minus y squared

wo die Beschreibung "Compute 2 mal x minus y squared" irgendwo geschrieben wird. Ich vermute, die Antwort auf meine Frage kann aus der Antwort auf die Frage "Wo ist der Ort, an dem die Beschreibung geschrieben werden soll?"


Wenn ich zum Beispiel in Python dasselbe machen wollte, könnte ich die Funktion definieren und die Beschreibung als Docstring schreiben:

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

Das würde meine Beschreibung sofort verfügbar machen, wenn ich tippe help(f) oder f? von IPython.


75
2017-11-06 19:40


Ursprung


Antworten:


Du kannst den ... benutzen @doc Makro in Julia Versionen 0.4 (Okt. 2015) und höher.

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

Bearbeiten: Wie von @Harrison Grodin hervorgehoben, unterstützen die Versionen 0.5 und höher eine abgekürzte Syntax sowie Markdown, LaTEX und ein paar andere 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

Es gibt mehr Details in der Dokumentation.


45
2017-12-01 05:58



In Julia v0.5 + können Sie eine mehrzeilige Zeichenfolge oberhalb der Funktionsdefinition schreiben. (Kein Bedarf für @doc nicht mehr.)

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

Weitere Informationen zum korrekten Formatieren Ihrer Docstrings finden Sie im offiziellen Julia Dokumentation.


10
2018-02-17 06:10