PEP 257 باللغة الروسية. (اتفاقية الوثائق)

حاشية. ملاحظة

التبرير

"توفر الاتفاقيات التقليدية الوضوح والاتساق وسهولة الصيانة وتعزز عادات البرمجة الجيدة. لكنهم لا يجبرونك على التصرف ضد إرادتك. هذه بيثون! "

تيم بيترز على comp.lang.python ، 2001-06-16

تخصيص

ما هو Docstring؟

1. تسمى حرفية السلسلة التي تحدث مباشرة بعد مهمة بسيطة على الوحدة أو الفئة أو __init__ "سلاسل توثيق السمة". (مستندات السمة)
   
2. يُطلق على حرفية السلسلة التي تحدث مباشرة بعد سطر آخر من التوثيق "سطور توثيق إضافية". (مستندات إضافية)

def f(x):
    """  docstring   __doc__ ."""
    """
     "additional docstrings",   , 
        Docutils.
    """
    return x**2

f.a = 1
""" "attribute docstrings"   : f.a"""

خطوط توثيق سطر واحد

def kos_root():
    """    root KOS"""
    global _kos_root
    if _kos_root: return _kos_root
    ...

• . .
• , . docstring .
• , .
• — «», . (« », « »), . , : « ...».
  
  

  « » «Return pathname» «Returns pathname». PEP-257 , .

• «», / ( ). :
  
  

  def function(a, b):
      """function(a, b) -> list"""
  

  
  , C ( ), . . - :
  
  

  def function(a, b):
      def function(a, b):
      """ X   ."""
  

  
  ( -, « X» !)
  
  

  , : « », «description» . , , .

  
  

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

     :
    real --   (  0.0)
    imag --   (  0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

معالجة التوثيق

def trim(docstring):
    if not docstring:
        return ''
    #     (  Python)
    #      :
    lines = docstring.expandtabs().splitlines()
    #    (   ):
    indent = sys.maxsize
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    #   (   ):
    trimmed = [lines[0].strip()]
    if indent < sys.maxsize:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    #       :
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    #    :
    return '\n'.join(trimmed)

def foo ():
    """
       .
    """

>>> print repr(foo.__doc__)
'\n        .\n    '
>>> foo.__doc__.splitlines()
['', '        .', '    ']
>>> trim(foo.__doc__)
'    .'

def foo():
    """ 
     .
    """

def bar():
    """
     
     .
    """