การใช้ javadoc สำหรับเอกสาร Python [ปิด]

ฉันกำลังเริ่มต้นด้วย Python และฉันมีพื้นหลัง PHP ที่แข็งแกร่งและใน PHP ฉันมีนิสัยที่จะใช้javadocเป็นแม่แบบเอกสาร

ฉันสงสัยว่าjavadocมีสถานที่เป็นdocstringเอกสารใน Python หรือไม่ อนุสัญญาที่จัดตั้งขึ้นและ / หรือสมาคมที่เป็นทางการที่นี่คืออะไร?

เช่นนี้เป็นสิ่งที่ซับซ้อนเกินกว่าที่จะเข้ากับความคิดของ Python หรือฉันควรจะพยายามรัดกุมที่สุดเท่าที่จะทำได้?

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

และถ้าฉันหมดแรงไปหน่อยฉันควรจะทำอะไรแบบนี้แทน (เอกสารส่วนใหญ่ไม่ได้พิมพ์ด้วย__doc__วิธี)?

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)

ดูที่รูปแบบreStructuredText (หรือเรียกอีกอย่างว่า "reST") ซึ่งเป็นรูปแบบมาร์กอัป plaintext / docstring และอาจเป็นที่นิยมมากที่สุดในโลก Python และคุณควรดูที่Sphinxซึ่งเป็นเครื่องมือในการสร้างเอกสารจาก reStructuredText (ใช้สำหรับเช่นเอกสาร Python เอง) สฟิงซ์รวมถึงความเป็นไปได้ที่จะดึงเอกสารจาก docstrings ในรหัสของคุณ (ดูsphinx.ext.autodoc ) และรับรู้รายการเขตข้อมูล reST ตามอนุสัญญาบางอย่าง นี่อาจเป็นวิธีที่ได้รับความนิยมมากที่สุด (หรือกำลังเป็นอยู่)

ตัวอย่างของคุณอาจมีลักษณะดังนี้:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

หรือขยายด้วยข้อมูลประเภท:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""

ทำตามคู่มือสไตล์ Google หลาม โปรดทราบว่าสฟิงซ์ยังสามารถแยกวิเคราะห์รูปแบบนี้โดยใช้ส่วนขยายของนโปเลียนซึ่งจะมาพร้อมกับสฟิงซ์ 1.3 (ซึ่งรองรับกับPEP257 ):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

ตัวอย่างที่นำมาจากเอกสารของนโปเลียนที่ลิงค์ด้านบน

ตัวอย่างที่ครอบคลุมในทุกประเภทของ docstrings ที่นี่

มาตรฐานสำหรับสตริงเอกสารหลามอธิบายไว้ในหลามการเพิ่มประสิทธิภาพของการเสนอ 257

ความคิดเห็นที่เหมาะสมสำหรับวิธีการของคุณจะเป็นอย่างไร

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """

ดูที่Documenting Pythonหน้า "มุ่งไปที่ผู้แต่งและผู้สร้างเอกสารสำหรับ Python"

กล่าวโดยย่อreStructuredTextคือสิ่งที่ใช้สำหรับการจัดทำเอกสาร Python คำแนะนำของนักพัฒนาซอฟต์แวร์ประกอบด้วยไพรเมอร์ reST คำแนะนำรูปแบบและคำแนะนำทั่วไปสำหรับการเขียนเอกสารที่ดี