Docstring

출처: www.python.org/dev/peps/pep-0257/

PEP 257 -- Docstring Conventions

What is a Docstring?

Docstring 이란 무엇인가?

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

Docstring은 문자열 리터럴String Literal의 한 종류이며(리터럴은 고정된 값을 의미한다), 모듈, 함수, 클래스 혹은 메소드의 정의 하는 코드 부분에서 선언 된다. Docstring은 __doc__의 형태로 해당 객체의 특징을 나타낸다.

 

All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings. A package may be documented in the module docstring of the __init__.py file in the package directory.

모든 모듈은 일반적인 경우에 docstring을 가지고 있으며, 함수나 클래스도 모듈에 의해 만들어졌다면 docstring을 가지고 있다. 초기 생성자 __init__와 같은 전역 메소드 또한 docstring을 가지고 있어야 한다. 패키지는, 패키지 디렉터리에 있는 __init__.py의 모듈 docstring에 문서화 되어 있다.

 

String literals occurring elsewhere in Python code may also act as documentation. They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to __doc__), but two types of extra docstrings may be extracted by software tools:

1. String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".
2. String literals occurring immediately after another docstring are called "additional docstrings"

문자열 리터럴=Docstring은 Python 코드 어디에서나 찾을 수 있으며 마치 주석과도 같은 효과를 지닌다. Python bytecode 컴파일러로 인식할 수 없으며, runtime object attribute로 접근할 수 없다.(주석은 __doc__로 할당받지만 Docstring은 그렇게 분류되지 않는다.) 그러나 다음과 같은 두개의 경우는 소프트웨어로 추출될 수도 있다.

1. 최상위의 모듈, 클래스, 혹은 생성자 메소드 __init__ 를 할당한 직후에 문자열 리터럴을 사용한 경우, attribute docstring으로 분류된다.
2. 기존의 Docstring 직후에 연속적으로 선언 된 docstring의 경우, additional docstring으로 분류된다.

For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""".

There are two forms of docstrings: one-liners and multi-line docstrings.

일관성을 위해서 항상 docstring의 앞 뒤에 큰따옴표를 3개 연속으로 사용하라. Docstring 중간에 백슬래쉬를 포함한다면 다음 형태로 큰따옴표를 사용하라. r"""raw triple double quotes""". 만약 유니코드를 Docstring에 사용한다면 다음 형태로 사용하라. u"""Unicode Triple-quoted string""".

 

 

예시.

한 줄 짜리 Docstring

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

확장성을 위해서 비록 한 줄 이라도 "을 3개 씩 써라.
Docstring 앞 뒤로는 빈 줄blank line을 만들어선 안된다.

 

// 아래 docstring에 대한 두 가지 설명은 제대로 이해하지 못하여 오역일 수도 있음을 알림. 

The docstring is a phrase ending in a period. 

Docstring은 온점.(period)으로 끝나는 구문이다. 

It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".

이 구문(==Docstring)에서는 함수나 메소드의 명령문로써의 결과를 서술해준다. 예를 들면, 이 함수는 이러한 값을 리턴한다, 이러한 기능을 한다. 그러나 함수나 메소드에 대한 자세한 묘사는 포함하지 않는다. 예를 들면, ~~ 라는 pathname으로 리턴된다.

The one-line docstring should NOT be a "signature" reiterating the function/method parameters (which can be obtained by introspection).

   --Introspection은 객체의 타입이나 유형과 같은 객체에 대한 정보를 런타임에 알게 되는 것을 의미한다.

   --Reflection은 introspection에서 더 나아가, 런타임에 객체에 접근하여, 객체를 조작하는 것을 의미한다.

 

Don't do:

이런 식으로 docstring을 쓰지 마라.

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

This type of docstring is only appropriate for C functions (such as built-ins), where introspection is not possible.

위와 같은 docstring은 introspection이 불가능한 C 함수에서나 성립이 가능하다.

 

However, the nature of the return value cannot be determined by introspection, so it should be mentioned.

그러나, 리턴 값의 본질을 고려한다면, 리턴 값은 introspection에 의해서 결정 되어서는 안되며, 별개로 정의되어야 한다.

 

The preferred form for such a docstring would be something like:

아래와 같은 형태로 docstring을 사용하여야 한다.

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

당연히 Do X는 코드가 아니라 function(a,b)에 대한 단순한 설명이다.

 

 

 

여러 줄로 이루어진 Docstring

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. The summary line may be on the same line as the opening quotes or on the next line. The entire docstring is indented the same as the quotes at its first line (see example below).

여러 줄로 이루어진 Docstring은 한 줄 짜리 Docstring과 같은 요약된 줄(line)로 이루어져 있으나, 뒤에 빈 줄blank line이 올 수 도 있고, 뒤에 더 자세한 설명이 올 수도 있다.(한 줄 짜리 Docstring은 앞 뒤로 빈 줄이 올 수 없음을 상기하라.) 이러한 요약된 줄은 색인index을 하는 도구에 의해 자동적으로 만들어 질 수도 있으며, 이 한줄이 어떠한 한 줄과는 연결되지만 나머지 docstring들 과는 빈 줄로 구별 될 수도 있다. 요약 줄은 첫번째 인용과 같은 라인 혹은 그 다음 라인에 위치한다. Docstring 전체는 인용과 같이 첫번째 줄에서 들여쓰기를 해야한다.(들여쓰기를 하는 법은 아래에 자세히 상술)

 

Insert a blank line after all docstrings (one-line or multi-line) that document a class -- generally speaking, the class's methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line.

Docstring이 class에 대한 설명 이라면 한 줄짜리이든 여러 줄 짜리이든, docstring의 끝에 빈 줄을 삽입한다. 클래스의 메소드는 빈 줄들로 구별되며 docstring은 여러 메소드들을 구분짓는 이정표off와 같은 기능을 한다.

The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a docstring should document the script's function and command line syntax, environment variables, and files. Usage messages can be fairly elaborate (several screens full) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.

 

The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's docstring.) The docstring for a package (i.e., the docstring of the package's __init__.py module) should also list the modules and subpackages exported by the package.

The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own 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
    ...

Unless the entire docstring fits on a line, place the closing quotes on a line by themselves. This way, Emacs' fill-paragraph command can be used on it.

 

 

Docstring의 들여쓰기

Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. Blank lines should be removed from the beginning and end of the docstring.

Since code is much more precise than words, here is an implementation of the algorithm:

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)

The docstring in this example contains two newline characters and is therefore 3 lines long. The first and last lines are blank:

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

To illustrate:

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

Once trimmed, these docstrings are equivalent:

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

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