Как сделать пользовательские описания функций ( "docstrings" ) доступными для julia REPL?

Как пользовательские функции (например, 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, я мог бы определить функцию и поставить описание как docstring:

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

что сделало бы мое описание доступным сразу после ввода help(f) или f? из IPython.

Ответы

Ответ 1

Макрос @doc можно использовать в @doc Julia 0.4 (октябрь 2015 г.) и выше.

% 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

Есть более подробная информация в документации.

Ответ 2

В Julia v0. 5+ вы можете написать многострочную строку над определением функции. (Больше не нужно @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.