python - كيفية توثيق طريقة مع المعلمة(ق)؟




documentation documentation-generation (5)

Docstrings مفيدة فقط في بيئات تفاعلية ، على سبيل المثال ، غلاف Python. عند توثيق الكائنات التي لن يتم استخدامها بشكل تفاعلي (على سبيل المثال ، الأجسام الداخلية ، عمليات رد اتصال الإطار) ، يمكنك أيضًا استخدام التعليقات المنتظمة. في ما يلي النمط الذي أستخدمه لتعليق التعليقات التي يتم إيقافها بإسهاب من العناصر ، كل منها على السطر الخاص بها ، حتى تعرف أن التعليق ينطبق على:

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

لا يمكنك القيام بهذا النوع من الأشياء مع التوثيق.

كيفية توثيق الطرق باستخدام المعلمات باستخدام سلاسل وثائق Python؟

تحرير: 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


إذا كنت تخطط لاستخدام Sphinx لتوثيق شفرتك ، فهي قادرة على إنتاج مستندات HTML منسقة بشكل جيد لمعلماتك مع ميزة "التواقيع" الخاصة بها. http://sphinx-doc.org/domains.html#signatures


الاتفاقيات:

أدوات:

تحديث: منذ 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 الاستفادة بسهولة منه.


بناءً على تجربتي ، فإن اتفاقيات docstring numpy (PEP257 superset) هي أكثر الاتفاقيات متبعة انتشارًا والتي تدعمها أيضًا أدوات ، مثل Sphinx .

مثال واحد:

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

ونظرًا لأن عمليات التوثيق تكون حرة ، فإنها تعتمد فعلاً على ما تستخدمه لتحليل الكود لإنشاء وثائق API.

أود أن أوصي بالتعرف على ترميز Sphinx ، لأنه يستخدم على نطاق واسع وأصبح المعيار الفعلي لتوثيق مشاريع Python ، ويرجع ذلك جزئيا إلى خدمة readthedocs.org الممتازة. لإعادة صياغة مثال من وثائق أبو الهول كمقتطف بايثون:

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

يدعم هذا الترميز cross-referencing بين المستندات والمزيد. لاحظ أن وثائق Sphinx تستخدم (على سبيل المثال) :py:attr: بينما يمكنك فقط استخدام :attr: عند التوثيق من شفرة المصدر.

وبطبيعة الحال ، هناك أدوات أخرى لتوثيق واجهات برمجة التطبيقات. هناك أكثر Doxygen الكلاسيكية التي تستخدم commands \param لكنها ليست مصممة خصيصا لتوثيق رمز Python مثل Sphinx.

لاحظ أن هناك سؤال مماثل مع إجابة مماثلة هنا ...





documentation-generation