Wie kann ich julia REPL benutzerdefinierte Funktionsbeschreibungen („docstrings“) zur Verfügung stellen?

Wie können benutzerdefinierte Funktionen (z. B. f) aussagekräftige Ausdrucke haben, wenn sie über die REPL mit ?foder überprüft werden?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 dies in eine Julia-Sitzung lade und versuche, help(f)erhalte ich Folgendes:

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

Was wäre, wenn ich stattdessen so etwas sehen wollte?

julia> help(f)
f

   Compute 2 times x minus y squared

wo die Beschreibung "2 mal x minus y im Quadrat berechnen" irgendwo geschrieben ist. Ich vermute, die Antwort auf meine Frage kann aus der Antwort auf die Frage "Wo ist der Ort, an dem die Beschreibung geschrieben werden sollte?" Bestimmt werden.

Wenn ich beispielsweise dasselbe in Python tun wollte, konnte ich die Funktion definieren und die Beschreibung als Dokumentzeichenfolge einfügen:

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

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

Sie können das @docMakro in Julia-Versionen 0.4 (Okt. 2015) und höher verwenden.

% 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 Versionen 0.5 und höher eine abgekürzte Syntax sowie Markdown, LaTEX und einige andere Extras:

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

Weitere Details finden Sie in der Dokumentation .

In Julia v0.5 + ( einschließlich neuerer Julia-Versionen wie 1.2+ ) können Sie eine mehrzeilige Zeichenfolge über der Funktionsdefinition schreiben. (Keine Notwendigkeit @docmehr.)

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 ordnungsgemäßen Formatieren Ihrer Dokumentzeichenfolgen finden Sie in der offiziellen Julia-Dokumentation .