如何使用户定义的功能描述("docstrings")可用于julia REPL? [英] How to make user defined function descriptions ("docstrings") available to julia REPL?

问题描述

使用?f或help(f)

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

For example imagine I write the following funciton

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

如果我将其加载到julia会话中并尝试help(f)，则会得到以下信息:

If I load this into a julia session and try help(f) I get the following:

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

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

What if instead I wanted to see something like

julia> help(f)
f

   Compute 2 times x minus y squared

其中计算2乘以x减y平方"的描述写在某处.我猜我的问题的答案可以由以下问题的答案确定:应该在哪里写描述?"

where the description "Compute 2 times x minus y squared" is written somewhere. I am guessing the answer to my question can be determined from the answer to the question "Where is the somewhere the description should be written?"

通过示例的方式，如果我想在python中做同样的事情，我可以定义函数并将描述作为文档字符串:

By way of example, if I wanted to do the same in python, I could define the function and put the description as a docstring:

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

，当我从IPython键入help(f)或f?时，将立即提供我的描述.

which would make my description immediately available when I type help(f) or f? from IPython.

推荐答案

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

You can use the @doc macro in Julia versions 0.4 (Oct. 2015) and above.

% 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和其他一些优点:

As pointed out by @Harrison Grodin, versions 0.5 and above support an abbreviated syntax as well as Markdown, LaTEX, and a few other 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

文档中有更多详细信息 .

There are more details in the documentation.

这篇关于如何使用户定义的功能描述("docstrings")可用于julia REPL?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！