4.7.6. Documentation Strings (docstrings)

함수 설명용 문자열

Here are some conventions about the content and formatting of documentation strings.
문서화 문자열안에 담기는 내용과 형식에는 몇가지 관습이 있습니다.

The first line should always be a short, concise summary of the object’s purpose. For brevity, it should not explicitly state the object’s name or type, since these are available by other means (except if the name happens to be a verb describing a function’s operation). This line should begin with a capital letter and end with a period. 첫번째 줄은 언제나 객체의 목적에 대해 짧고 간결하게 요약해야 합니다. 간결함을 위해, 객체의 이름이나 유형을 명시하지 마십시오. 다른 의미로 받아들여질 가능성이 있기 때문입니다. 이 첫번째 줄은 대문자로 시작하고 짧게 끝나야 합니다.

If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description. The following lines should be one or more paragraphs describing the object’s calling conventions, its side effects, etc.
설명용 문자열이 여러 줄인 경우, 첫번째 줄의 요약과 나머지 내용을 시각적으로 분리하기 위해, 두번째 줄은 반드시 비어있어야 합니다. 그 다음 줄들은 하나 또는 그 이상의 문단이어야 합니다. 문단들은 객체 호출 규칙이나 부작용 등을 설명합니다.

The Python parser does not strip indentation from multi-line string literals in Python, so tools that process documentation have to strip indentation if desired. This is done using the following convention. The first non-blank line after the first line of the string determines the amount of indentation for the entire documentation string. (We can’t use the first line since it is generally adjacent to the string’s opening quotes so its indentation is not apparent in the string literal.) Whitespace “equivalent” to this indentation is then stripped from the start of all lines of the string. Lines that are indented less should not occur, but if they occur all their leading whitespace should be stripped. Equivalence of whitespace should be tested after expansion of tabs (to 8 spaces, normally).
파이썬의 parser는 여러 줄에 걸친 문자열에서 들여쓰기를 제거하지 않습니다. 그렇기 때문에 설명을 처리하는 도구는 필요한 경우 들여쓰기를 제거해야 합니다. 들여쓰기 제거는 다음 규칙대로 진행합니다.

첫번째 줄(요약) 이후에 시작되는 첫 줄은 전체 설명용 문자열의 들여쓰기 양을 결정합니다. 요약을 위해 사용된 첫번째 줄은 대부분의 경우 docstring을 여는 기호 """와 가까이 있기 때문에 들여쓰기가 얼마나 된 것인지 알아보기 힘듭니다. 이 줄에 사용된 들여쓰기는 뒤따르는 모든 문자열에 적용되지 않습니다.
덜 들여써진 줄이 있어서는 안되며, 만약 그런 줄이 생겼을 경우 앞서 진행된 모든 들여쓰기가 지워져야 합니다.
들여쓰기는 tab키의 설정을 확인한 뒤 맞추는 것이 좋습니다. (tab키는 일반적으로 space 키를 8번 누른 것과 동일하게 작동합니다.)

Here is an example of a multi-line docstring:
아래는 여러 줄로 구성된 docstring 의 예 입니다.

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.