如何使用户定义的功能描述(“文档字符串”)可用于julia REPL?


91

f通过REPL使用?f或进行检查时,用户定义的函数(例如)如何具有有意义的打印输出help(f)

例如,假设我写了以下函数

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

如果我将其加载到julia会话中并尝试help(f)获取以下内容:

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

如果我想看到类似的东西怎么办

julia> help(f)
f

   Compute 2 times x minus y squared

描述“计算2乘以x减y平方”。我猜我的问题的答案可以由以下问题的答案确定:“说明应该写在哪里?”


举例来说,如果我想在python中做同样的事情,我可以定义函数并将描述作为文档字符串:

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

当我输入文字help(f)f?从IPython输入文字时,这些说明将立即可用。


11
我认为您还不能做到。参见例如:github.com/JuliaLang/julia/issues/3988
ivarne

2
这将很快发生。看到这里的
spencerlyon2 2014年

Answers:


56

您可以@doc在Julia版本0.4(2015年10月)及更高版本中使用该宏。

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

编辑:正如@Harrison Grodin所指出的那样,版本0.5及更高版本支持缩写语法以及Markdown,LaTEX和其他一些优点:

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

文档中有更多详细信息。


30

在Julia v0.5 +(包括最新的Julia版本,如1.2+)中,您可以在函数定义上方编写多行字符串。(不再需要@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

有关正确格式化文档字符串的更多信息,请参见官方Julia文档

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.