julia - 如何使用户定义的函数描述 ("docstrings") 可用于 julia REPL？

Question

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

例如假设我写了以下函数

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

如果我将其加载到 julia session 中并尝试 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

当我从 IPython 中输入 help(f) 或 f? 时，我的描述会立即可用。

Answer 1

您可以使用@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

还有更多详情in the documentation .