Python Documentation Rules(파이썬 문서화 규칙)

docstring은 모듈, 함수, 클래스 또는 메소드 정의의 첫번째 명령문으로 발생하는 문자열 리터럴이며, 

해당 객체의 __doc__ 특수 속성으로 접근할 수 있습니다.

모든 모듈은 일반적으로 docstring이 있어야 하며, 모든 함수와 모듈에서 내보내는 모든 기능 및 클래스에도 docstring이 

있어야 합니다.

Public 메소드(_init__ 생성자 포함)에도 문서화가 있어야 합니다.

패키지는 패키지 디렉토리에 있는 __init__.py 파일의 모듈 문서화 될 수 있습니다.

파이선 코드의 문자열 리터럴은 문서화 역할을 할 수도 있습니다.

Python Bytecode 컴파일러에 의해 인식되지 않고 런타임 객체 속성(즉, _doc_에 할당되지 않음)으로 접근할 수 없지만, 소프트웨어 도구에 의해 두 가지 유형의 추가 문서 제약이 추출될 수 있습니다.

1. 모듈, 클래스 또는 _init__ 메서드의 최상위 수준에서 간단한 할당 직후에 발생하는 문자열 리터럴을 "특수 문서"라고

합니다.

2. 다른 문서 문자열 직후에 발생하는 문자열 문자열을 "추가 문서 문자열"이라고 합니다.

자세한 설명은 PEP 257, "Docstring Conventions" 가이드를 참고 하십시오.

PEP 257 – Docstring Conventions | peps.python.org

 

일관성을 유지하려면 항상 세개의 큰따옴표(""")를 사용하세요.

"""
Text Sample
"""

백슬래시(\)가 존재할 경우 r을 붙여 사용하고

r"""raw  triple double  quotes""

유니코드 문서일 경우 u를 붙여 사용하세요.

u"""Unicode   triple-quoted   strings"""

docstring은 한줄 표현과 여러줄 표현이 있습니다.

 

한줄 docstring

명확한 경우 한줄로 표현 합니다.

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

 

- 한줄이라도 세개의 큰 따옴표를 사용합니다. 이렇게 하면 나중에 쉽게 확장할 수 있습니다.
- 마지막 닫힘 표시는 시작과 같은 줄에 위치하는것이 한줄표현으로 더 나아 보입니다.
- docstring 전후에 빈줄이 없어야 합니다.
- docstring은 마침표로 끝나는 문구입니다.

명령어로 함수 또는 메소드들의 효과를 규정하고 있다.

("Do this", "Return that"), 예를 들어 "Returns the pathname ..." 이런 설명은 쓰지 마세요.
- 한줄 표현시 함수/메소드의 매개변수를 반복 하지마세요.

 

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

- 이러한 유형의 docstring은 C 함수에만 적합하지만 반환되는 결과의 속성은 언급해하므로 이러한 docstring의 기본 

형태는 다음과 같습니다.

 

def function(a, b):
    """Do X and return a list."""

-  물론 "Do X" 는 유용한 설명으로 대체되어야 합니다.

 

여러줄 docstrings

여러줄 docstrings 은 한줄 docstring과 마찬가지로 요약 행으로 구성되며, 빈 줄 다음에 상세 설명이 뒤따릅니다. 

요약 행은 자동 색인 도구에 의해 사용될 수 있어 한 줄에 기재하고 빈 줄로 분리하는 것이 중요합니다.

요약 행은 시작 따옴표와 같은 줄 또는 다음 줄에 있을 수 있습니다.

전체 docstring은 첫 번째 줄의 따옴표와 동일하게 입력됩니다.

 

모든 docstrings (한줄 또는 여러줄) 후에 공백 줄을 삽입합니다. 

일반적으로 클래스의 메서드는 하나의 공백 라인으로 서로 분리되며, 첫 번째 메서드에서 공백 라인으로 간격을 띄워야 

합니다.

 

스크립트 (독립 실행 형 프로그램)의 docstring은 스크립트가 부정확하거나 누락 된 인수

(또는 "도움말" 에 대한 "-h" 옵션) 로 호출 될 때  출력되는 메시지로 사용할 수 있어야합니다.

이러한 docstring은 스크립트의 함수 및 명령줄 구문, 환경 변수 및 파일을 문서화해야합니다. 

사용 메시지는 상당히 상세할 수 있으며 (여러 화면 가득) 새 사용자가 명령을 올바르게 사용하기에 충분해야하며 

정교한 사용자에 대한 모든 옵션 및 인수에 대한 완전한 빠른 참조가 있어야합니다.

 

모듈의 docstring은 일반적으로 모듈에서 내보내는 클래스, 예외 및 기능 (및 기타 모든 객체) 을 각각 한 줄의 요약으로 

나열해야합니다. (이 요약은 일반적으로 객체의 docstring 요약보다 상세하지 않음)
패키지에 대한 docstring(즉, 패키지의 __init__.py 모듈의 docstring)도 패키지에서 내보낸 모듈 및 하위 패키지를 

나열해야합니다.

함수 또는 메소드의 docstring은 행위를 요약하고 인수, 반환 값, 부작용, 예외사항 및 호출 할 수있는 제한 사항

(해당되는 경우 모두) 을 문서화해야합니다.
선택적 인수를 표시해야 합니다. 

키워드 인수가 인터페이스의 일부인지 여부를 문서화해야합니다.

클래스의 docstring은 행위를 요약하고 공용 메서드와 인스턴스 변수를 나열해야합니다.
클래스가 하위 클래스를 포함하도록 되어 있고 하위 클래스를 위한 추가 인터페이스가 있는 경우,이 인터페이스는

별도로 (docstring에) 나열되어야합니다.
클래스 생성자는 __init__ 메서드에 대한 docstring에 문서화되어야합니다. 

개별 방법은 자체 문서 문자열에 의해 문서화되어야합니다.

한 클래스가 다른 클래스를 하위 클래스로 분류하고 그 클래스의 동작이 대부분 해당 클래스에서 상속되는 경우, 

해당 클래스의 docstring은 이것을 언급하고 차이점을 요약해야 합니다.
하위클래스 메소드가 슈퍼클래스 메소드를 대체하고 슈퍼클래스 메소드를 호출하지 않는다는 것을 나타내기 

위해서는 "override"를 사용하고,
하위클래스 메소드가 슈퍼클래스 메소드를 호출하는 경우를 나타내려면 "extend"를 사용합니다.

텍스트를 실행할 때 대문자로 함수 또는 메소드의 인수를 언급하는 Emacs 규칙을 사용하지 마십시오.
Python은 대소문자를 구분하며, 인수 이름은 키워드 인수에 사용할 수 있으므로, docstring은 올바른 인수 이름을 

문서화해야 합니다. 
각 인수를 별도의 줄에 나열하는 것이 가장 좋습니다. 

예를 들면 아래와 같습니다.

 

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

- 여러줄 docstrings 사용시 닫는 따옴표를 마지막 줄에 삽입해야 합니다. 

이렇게 하면 Emacs'fill-paragraph 명령어를 사용할 수 있습니다.

 

들여쓰기 처리

docstring 처리 도구는 첫 번째 라인 이후 모든 비고정 라인의 최소 들여쓰기와 동일한 양의 문서 문자열 두 번째 및 추가

라인에서 들여쓰기를 제거합니다.
docstring의 첫 번째 줄(즉, 첫 번째 줄까지)에 있는 모든 들여쓰기 부분은 제거되며, 이후 들여쓰기는 유지 됩니다.
docstring의 시작과 끝에서 빈 줄은 제거해야 합니다.

 

코드는 단어보다 훨씬 더 정확하기 때문에 알고리즘의 구현은 다음과 같습니다.

def trim(docstring):
    if not docstring:
        return ''
    # Convert tabs to spaces (following the normal Python rules)
    # and split into a list of lines:
    lines = docstring.expandtabs().splitlines()
    # Determine minimum indentation (first line doesn't count):
    indent = sys.maxint
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    # Remove indentation (first line is special):
    trimmed = [lines[0].strip()]
    if indent < sys.maxint:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    # Strip off trailing and leading blank lines:
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    # Return a single string:
    return '\n'.join(trimmed)

- 아래 예제에서 docstring은 두 개의 새로운 줄 문자를 포함하므로 3줄이다.

첫 번째 줄과 마지막 줄은 비어 있다.

 

def foo():
    """
    This is the second line of the docstring.
    """

 

설명하자면

>>> print repr(foo.__doc__)
'\n This is the second line of the docstring.\n '
>>> foo.__doc__.splitlines()
['', ' This is the second line of the docstring.', ' ']
>>> trim(foo.__doc__)
'This is the second line of the docstring.'

 

일단 다듬어지면 docstrings은 다음과 같습니다.

def foo():
    """ A multi-line
    docstring.
    """
def bar():
    """
    A multi-line
    docstring.
    """