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

Question

Как определяемые пользователем функции (например f) имеют значимые распечаток при осмотрены через РЕПЛ с помощью ?f или help(f)

Например представьте я пишу следующую Funciton

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 

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

Answer 1

Вы можете использовать макрос @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. 

Edit: Как отметил @Harrison Гродин, версии 0.5 и выше поддержки сокращенный синтаксис, а также Markdown, латексные и некоторые другие лакомства:

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

Answer 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 Documentation.