วิธีการจัดทำเอกสารวิธีการที่มีพารามิเตอร์?

วิธีการทำเอกสารวิธีการที่มีพารามิเตอร์โดยใช้สตริงเอกสารคู่มือของงูใหญ่?

แก้ไข: PEP 257ให้ตัวอย่างนี้:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

นี่เป็นข้อตกลงที่นักพัฒนางูหลามส่วนใหญ่ใช้หรือไม่

Keyword arguments:
<parameter name> -- Definition (default value if any)

ฉันคาดหวังบางอย่างที่เป็นทางการมากกว่าเช่น

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

สภาพแวดล้อม : Python 2.7.1

จากประสบการณ์ของผมประชุม docstring numpy (PEP257 เซ็ต) เป็นกันอย่างกว้างขวางที่สุดการแพร่กระจายตามอนุสัญญาว่าได้รับการสนับสนุนโดยเครื่องมือเช่นสฟิงซ์

ตัวอย่างหนึ่ง:

Parameters
----------
x : type
    Description of parameter `x`.

เนื่องจากเอกสารมีรูปแบบอิสระจึงขึ้นอยู่กับสิ่งที่คุณใช้ในการแยกวิเคราะห์รหัสเพื่อสร้างเอกสาร API

ฉันขอแนะนำให้ทำความคุ้นเคยกับมาร์กอัป Sphinxเนื่องจากมีการใช้กันอย่างแพร่หลายและกลายเป็นมาตรฐาน de-facto สำหรับการทำเอกสารโครงการ Python ส่วนหนึ่งเป็นเพราะบริการreadthedocs.org ที่ยอดเยี่ยม ในการถอดความตัวอย่างจากเอกสารสฟิงซ์เป็นตัวอย่างข้อมูล Python:

def send_message(sender, recipient, message_body, priority=1):
   '''
   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   '''

มาร์กอัพนี้รองรับการอ้างอิงโยงระหว่างเอกสารและอื่น ๆ โปรดทราบว่าเอกสารประกอบสฟิงซ์ใช้ (เช่น) :py:attr:ในขณะที่คุณสามารถใช้:attr:เมื่อทำเอกสารจากซอร์สโค้ด

โดยปกติมีเครื่องมืออื่น ๆ สำหรับเอกสาร API มีDoxygenแบบคลาสสิกมากขึ้นซึ่งใช้\param คำสั่งแต่สิ่งเหล่านั้นไม่ได้ถูกออกแบบมาโดยเฉพาะเพื่อบันทึกรหัส Python อย่าง Sphinx

โปรดทราบว่ามีคำถามที่คล้ายกันซึ่งมีคำตอบที่คล้ายกันที่นี่ ...

การประชุม:

• PEP 257 ข้อตกลง Docstring
• PEP 287 reStructuredText Docstring Format

เครื่องมือ

• Epydoc: การสร้างเอกสาร API อัตโนมัติสำหรับ Python
• sphinx.ext.autodoc - รวมเอกสารจาก docstrings
• PyCharm มีการสนับสนุนที่ดีสำหรับ docstrings

อัปเดต: ตั้งแต่ Python 3.5 คุณสามารถใช้คำแนะนำประเภทซึ่งเป็นไวยากรณ์ขนาดกะทัดรัดและเครื่องอ่านได้:

from typing import Dict, Union

def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
    """
    Explanation: this function takes two arguments: `i` and `d`.
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys
    and values that can be either `str` or `int`.

    The return type is `int`.

    """

ประโยชน์หลักของไวยากรณ์นี้คือมันถูกกำหนดโดยภาษาและมันไม่ชัดเจนดังนั้นเครื่องมือเช่น PyCharm สามารถใช้ประโยชน์จากมันได้อย่างง่ายดาย

python doc strings เป็นแบบฟรีฟอร์มคุณสามารถจัดทำเอกสารได้ตามที่คุณต้องการ

ตัวอย่าง:

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

ตอนนี้มีการประชุมบางส่วน แต่หลามไม่บังคับใช้ใด ๆ บางโครงการมีการจัดการประชุมของตนเอง เครื่องมือบางอย่างในการทำงานกับ docstrings ก็เป็นไปตามอนุสัญญาเฉพาะ

หากคุณวางแผนที่จะใช้สฟิงซ์เพื่อจัดทำเอกสารรหัสของคุณก็สามารถผลิตเอกสาร HTML ที่จัดรูปแบบได้อย่างดีสำหรับพารามิเตอร์ของคุณด้วยคุณสมบัติ 'ลายเซ็น' http://sphinx-doc.org/domains.html#signatures

ที่สำคัญคือตามที่คำตอบอื่น ๆ ที่นี่ชี้ให้เห็นอาจจะไปด้วยวิธีสฟิงซ์เพื่อให้คุณสามารถใช้สฟิงซ์เพื่อสร้างเอกสารแฟนซีเหล่านั้นในภายหลัง

ที่ถูกกล่าวว่าฉันเองไปกับสไตล์ความคิดเห็นแบบอินไลน์เป็นครั้งคราว

def complex(  # Form a complex number
        real=0.0,  # the real part (default 0.0)
        imag=0.0  # the imaginary part (default 0.0)
        ):  # Returns a complex number.
    """Form a complex number.

    I may still use the mainstream docstring notation,
    if I foresee a need to use some other tools
    to generate an HTML online doc later
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    other_code()

อีกหนึ่งตัวอย่างที่นี่พร้อมด้วยรายละเอียดเล็ก ๆ น้อย ๆ ที่บันทึกไว้แบบอินไลน์:

def foo(  # Note that how I use the parenthesis rather than backslash "\"
          # to natually break the function definition into multiple lines.
        a_very_long_parameter_name,
            # The "inline" text does not really have to be at same line,
            # when your parameter name is very long.
            # Besides, you can use this way to have multiple lines doc too.
            # The one extra level indentation here natually matches the
            # original Python indentation style.
            #
            # This parameter represents blah blah
            # blah blah
            # blah blah
        param_b,  # Some description about parameter B.
            # Some more description about parameter B.
            # As you probably noticed, the vertical alignment of pound sign
            # is less a concern IMHO, as long as your docs are intuitively
            # readable.
        last_param,  # As a side note, you can use an optional comma for
                     # your last parameter, as you can do in multi-line list
                     # or dict declaration.
        ):  # So this ending parenthesis occupying its own line provides a
            # perfect chance to use inline doc to document the return value,
            # despite of its unhappy face appearance. :)
    pass

ประโยชน์ (ตามที่ @ mark-horvath ชี้ให้เห็นแล้วในความคิดเห็นอื่น) คือ:

• สิ่งสำคัญที่สุดคือพารามิเตอร์และเอกสารของพวกเขาอยู่ด้วยกันเสมอซึ่งนำประโยชน์ดังต่อไปนี้:
• พิมพ์น้อยลง (ไม่จำเป็นต้องทำซ้ำชื่อตัวแปร)
• บำรุงรักษาง่ายขึ้นเมื่อเปลี่ยน / ลบตัวแปร จะไม่มีย่อหน้า doc เอกสารพารามิเตอร์เด็กกำพร้าหลังจากที่คุณเปลี่ยนชื่อบางพารามิเตอร์
• และง่ายต่อการค้นหาความคิดเห็นที่ขาดหายไป

ตอนนี้บางคนอาจคิดว่าสไตล์นี้ดู "น่าเกลียด" แต่ฉันจะบอกว่า "น่าเกลียด" เป็นคำอัตนัย วิธีที่เป็นกลางมากขึ้นคือการพูดสไตล์นี้ไม่ได้เป็นกระแสหลักดังนั้นจึงอาจดูไม่ค่อยคุ้นเคยสำหรับคุณ อีกครั้ง "ความสะดวกสบาย" ยังเป็นคำอัตนัย แต่ประเด็นคือประโยชน์ทั้งหมดที่อธิบายไว้ข้างต้นมีวัตถุประสงค์ คุณไม่สามารถบรรลุเป้าหมายได้หากคุณทำตามวิธีมาตรฐาน

หวังว่าสักวันในอนาคตจะมีเครื่องมือสร้างเอกสารซึ่งสามารถใช้รูปแบบอินไลน์เช่นกัน ที่จะผลักดันการยอมรับ

PS: คำตอบนี้มาจากความชอบของฉันในการใช้ความคิดเห็นแบบอินไลน์เมื่อใดก็ตามที่ฉันเห็นว่าเหมาะสม ฉันใช้สไตล์อินไลน์เดียวกันเพื่อจัดทำเอกสารพจนานุกรมด้วย

คำตอบประเภทคำแนะนำ ( https://stackoverflow.com/a/9195565/2418922 ) ซึ่งให้วิธีที่มีโครงสร้างที่ดีกว่าสำหรับประเภทเอกสารของพารามิเตอร์นอกจากนี้ยังมีลักษณะที่มีโครงสร้างในการจัดทำเอกสารทั้งประเภทและคำอธิบายของพารามิเตอร์:

def copy_net(
    infile: (str, 'The name of the file to send'),
    host: (str, 'The host to send the file to'),
    port: (int, 'The port to connect to')):

    pass

ตัวอย่างที่ใช้จาก: https://pypi.org/project/autocommand/

เอกสารประกอบมีประโยชน์เฉพาะภายในสภาพแวดล้อมแบบโต้ตอบเช่น Python shell เมื่อทำเอกสารวัตถุที่จะไม่ถูกใช้แบบโต้ตอบ (เช่นวัตถุภายในกรอบการเรียกกลับ) คุณอาจใช้ความคิดเห็นปกติเช่นกัน นี่คือสไตล์ที่ฉันใช้สำหรับแขวนความคิดเห็นที่เยื้องกับรายการต่าง ๆ ในแต่ละบรรทัดเพื่อให้คุณรู้ว่าความคิดเห็นนั้นถูกนำไปใช้กับ:

def Recomputate \
  (
    TheRotaryGyrator,
      # the rotary gyrator to operate on
    Computrons,
      # the computrons to perform the recomputation with
    Forthwith,
      # whether to recomputate forthwith or at one's leisure
  ) :
  # recomputates the specified rotary gyrator with
  # the desired computrons.
  ...
#end Recomputate

คุณไม่สามารถทำสิ่งนี้กับเอกสารได้