파이썬 모듈 docstring에 무엇을 넣어야합니까? [닫은]

167

좋아, 그래서 PEP 8 과 PEP 257을 읽었고 함수와 클래스를 위해 많은 docstring을 썼지 만 모듈 docstring에 무엇이 들어 가야할지 확실하지 않습니다. 최소한 모듈이 내보내는 함수와 클래스를 문서화해야한다고 생각했지만 저자 이름, 저작권 정보 등을 나열하는 몇 가지 모듈도 보았습니다. 모든 사람이 좋은 파이썬 docstring을 어떻게 해야하는지에 대한 예가 있습니까? 구조화되어 있습니까?

python documentation module

답변:

183

help(yourmodule)대화식 통역사의 안내를받는 사람에 대해 생각해보십시오. 무엇 을 알고 싶어 합니까? (정보를 추출하고 표시하는 다른 방법은 help정보량 측면에서 대략 동일합니다 ). 그래서 당신이 가지고 있다면 x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

그때:

>>> import x; help(x)

보여줍니다 :

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

보시다시피, 클래스에 대한 자세한 정보 (그리고 여기에 표시하지는 않지만 기능도 있습니다)는 이미 해당 컴포넌트의 docstring에 포함되어 있습니다. 모듈 자체의 docstring은 그것들을 매우 요약하여 설명하고 (모두 있다면) 모듈이 전체적으로 당신을 위해 할 수있는 것에 대한 간결한 요약에 중점을 두어야합니다 (함수와 클래스가 이상적으로 doctested 예제를 가지고 있어야하는 것처럼) 그들의 docstrings).

저자 이름 및 저작권 / 라이센스와 같은 메타 데이터가 모듈 사용자에게 어떻게 도움이되는지 보지 못합니다. 모듈을 재사용하거나 수정해야하는지 여부를 고려하는 데 도움이 될 수 있기 때문에 주석을 달 수 있습니다.

— 알렉스 마르 텔리
소스

따라서 모듈 상단의 주석에 작성자, 저작권 등을 포함시키는 것이 일반적입니까?

@ 007brendan, 그것은 일반적인 관행입니다.

— Alex Martelli

@IfLoop 나는 help()단순히 코드를 읽는 사용자보다 인터프리터 에서 메소드 를 사용하는 사용자가 더 많다고 의심합니다 .

— confused00

염두에 두어야 할 가장 중요한 것은 이유 입니다. 무언가를 문서화하는 것은 잘 작성된 코드의 작업입니다. 문서화 작업이 왜 필요한지 문서화.

— Erik Aronesty

사양 을 인용하려면 :

스크립트 의 docstring (독립형 프로그램)은 "usage"메시지로 사용할 수 있어야합니다. 스크립트가 부정확하거나 누락 된 인수 (또는 "help"에 대해 "-h"옵션)로 호출 될 때 인쇄됩니다. 이러한 docstring은 스크립트의 기능과 명령 행 구문, 환경 변수 및 파일을 문서화해야합니다. 사용법 메시지는 상당히 정교 할 수 있으며 (여러 화면이 꽉 참) 새 사용자가 명령을 올바르게 사용하기에 충분해야하며 정교한 사용자를위한 모든 옵션과 인수에 대한 완전한 빠른 참조가 필요합니다.

모듈 의 docstring 은 일반적으로 모듈에 의해 익스포트 된 클래스, 예외 및 함수 (및 기타 오브젝트)를 각각 한 줄 요약하여 나열해야합니다. (이 요약은 일반적으로 객체의 docstring에있는 요약 라인보다 덜 자세합니다.) 패키지의 docstring (즉, 패키지 __init__.py모듈 의 docstring)에는 패키지에서 내 보낸 모듈 및 하위 패키지도 나열되어야합니다.

클래스 의 docstring 은 그 동작을 요약하고 공개 메소드와 인스턴스 변수를 나열해야합니다. 클래스가 서브 클래스로 작성되고 서브 클래스에 대한 추가 인터페이스가있는 경우이 인터페이스는 개별적으로 (docstring에) 나열되어야합니다. 클래스 생성자는 해당 __init__메소드 의 docstring에 문서화되어야합니다 . 개별 메소드는 자체 문서화 문자열로 문서화해야합니다.

함수 나 메소드 의 docstring은 마침표로 끝나는 문구입니다. 함수 나 메소드의 효과를 설명이 아닌 명령 ( "이것", "반환")으로 규정합니다. 예를 들어 "경로 이름을 반환합니다 ..."라고 쓰지 마십시오. 함수 나 메소드에 대한 여러 줄로 이루어진 문자열은 그 동작을 요약하고 인수, 반환 값, 부작용, 발생 된 예외 및 호출 가능시기에 대한 제한 사항 (해당되는 경우 모두)을 문서화해야합니다. 선택적 인수가 표시되어야합니다. 키워드 인수가 인터페이스의 일부인지 여부를 문서화해야합니다.

— 레미
소스