Làm cách nào để cung cấp các mô tả chức năng do người dùng xác định (“docstrings”) cho julia REPL?

Làm thế nào để các chức năng do người dùng xác định (giả sử f) có các bản in có ý nghĩa khi được kiểm tra qua REPL bằng cách sử dụng ?fhoặchelp(f)

Ví dụ, hãy tưởng tượng tôi viết funciton sau

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

Nếu tôi tải điều này vào một phiên julia và thử, help(f)tôi nhận được như sau:

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

Điều gì sẽ xảy ra nếu thay vào đó tôi muốn xem một cái gì đó như

julia> help(f)
f

   Compute 2 times x minus y squared

trong đó mô tả "Tính 2 lần x trừ y bình phương" được viết ở đâu đó. Tôi đoán câu trả lời cho câu hỏi của tôi có thể được xác định từ câu trả lời cho câu hỏi "Đâu là nơi mà mô tả nên được viết?"

Ví dụ: nếu tôi muốn làm điều tương tự trong python, tôi có thể xác định hàm và đặt mô tả dưới dạng docstring:

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

điều này sẽ làm cho mô tả của tôi có sẵn ngay lập tức khi tôi nhập help(f)hoặc f?từ IPython.

Bạn có thể sử dụng @docmacro trong Julia phiên bản 0.4 (tháng 10 năm 2015) trở lên.

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

Chỉnh sửa: Như đã chỉ ra bởi @Harrison Grodin, các phiên bản 0.5 trở lên hỗ trợ cú pháp viết tắt cũng như Markdown, LaTEX và một số tính năng bổ sung khác:

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

Có nhiều chi tiết hơn trong tài liệu .

Trong Julia v0.5 + ( bao gồm các Phiên bản Julia gần đây hơn như 1.2+ ), bạn có thể viết một chuỗi nhiều dòng phía trên định nghĩa hàm. (Không cần @docnữa.)

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

Để biết thêm thông tin về cách định dạng đúng docstrings của bạn, hãy xem Tài liệu chính thức của Julia .