如何使用户定义的函数描述(“文档字符串")可用于 julia REPL? [英] How to make user defined function descriptions ("docstrings") available to julia REPL?

问题描述

How can user defined functions (say f) have meaningful printouts when inspected via the REPL using ?for help(f)

For example imagine I write the following funciton

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

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

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

---

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

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

解决方案

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.

Edit: 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.

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