วิธีทำให้คำอธิบายฟังก์ชันที่ผู้ใช้กำหนดเอง (“ docstrings”) พร้อมใช้งานสำหรับ julia REPL

ฟังก์ชันที่ผู้ใช้กำหนดเอง (พูดf) จะมีงานพิมพ์ที่มีความหมายได้อย่างไรเมื่อตรวจสอบผ่าน REPL โดยใช้?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 ฉันสามารถกำหนดฟังก์ชันและใส่คำอธิบายเป็น docstring:

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

ซึ่งจะทำให้คำอธิบายของฉันใช้งานได้ทันทีเมื่อฉันพิมพ์help(f)หรือf?จาก IPython

คุณสามารถใช้@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

มีรายละเอียดเพิ่มเติมในเอกสารประกอบ

ใน Julia v0.5 + ( รวมถึงเวอร์ชันล่าสุดของ Julia เช่น 1.2+ ) คุณสามารถเขียนสตริงหลายบรรทัดเหนือนิยามฟังก์ชันได้ (ไม่จำเป็น@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

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการจัดรูปแบบถูกต้อง docstrings ของคุณให้ดูเป็นทางการเอกสารจูเลีย