python module docstring에 넣을 내용
네, PEP 8과 PEP 257을 모두 읽었고 함수 및 클래스에 대한 문서스트링도 많이 썼는데 모듈 문서스트링에 뭐가 들어가야 할지 잘 모르겠어요.적어도 모듈이 내보내는 기능과 클래스는 문서화해야 한다고 생각했지만, 작성자 이름, 저작권 정보 등을 나열하는 모듈도 몇 개 보았습니다.좋은 python docstring을 어떻게 구조화해야 하는지 예를 들어보신 분 있나요?
가 하는 것을 해 보세요.help(yourmodule)인터랙티브 인터프리터의 프롬프트에 따라 - 무엇을 알고 싶은가? (정보를 추출하여 표시하는 다른 방법은 대략 다음과 같습니다.)help정보량의 관점에서). 래래 so so so 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은 스크립트가 잘못된 인수 또는 누락된 인수(또는 "도움말"의 경우 "-h" 옵션을 사용하여 호출되었을 때 출력되는 "사용" 메시지로 사용할 수 있어야 합니다.이러한 docstring은 스크립트의 기능 및 명령줄 구문, 환경 변수 및 파일을 문서화해야 합니다.사용현황 메시지는 매우 상세할 수 있으며(몇 개의 화면 가득), 새로운 사용자가 명령을 올바르게 사용할 수 있을 뿐만 아니라 고급 사용자의 모든 옵션과 인수를 빠르게 참조할 수 있습니다.
모듈의 docstring에는 일반적으로 모듈에 의해 내보내는 클래스, 예외 및 함수(및 기타 객체)가 각각1줄로 요약되어 표시됩니다(이러한 요약은 일반적으로 객체의 docstring 요약 행보다 상세하지 않습니다).패키지의 docstring(즉, 패키지의 docstring)
__init__.pymodule)에는 패키지에 의해 내보낸 모듈과 서브패키지도 기재되어 있습니다.클래스의 docstring은 해당 동작을 요약하고 공개 메서드와 인스턴스 변수를 나열해야 합니다.클래스가 서브클래스를 의도하고 서브클래스의 추가 인터페이스가 있는 경우 이 인터페이스는 (docstring에) 따로 나열해야 합니다.클래스 생성자는 다음 항목에 대해 문서 문자열에 문서화해야 합니다.
__init__방법.개별 방법은 문서 문자열로 문서화해야 합니다.
함수 또는 메서드의 docstring은 마침표로 끝나는 구문입니다.함수 또는 메서드의 효과는 설명으로서가 아니라 명령어("Do this", "Return that")로서 규정됩니다.예를 들어, "Returns pathname..."이라고 쓰지 마십시오.함수 또는 메서드에 대한 다중 행-docstring은 해당 동작을 요약하여 인수, 반환 값, 예외 발생 및 호출할 수 있는 제한 사항을 문서화해야 합니다.d(해당하는 경우 모두)옵션 인수를 지정해야 합니다.키워드 인수가 인터페이스의 일부인지 여부를 문서화해야 합니다.
언급URL : https://stackoverflow.com/questions/2557110/what-to-put-in-a-python-module-docstring
'programing' 카테고리의 다른 글
| kernel.h의 min 매크로에서 "(min) (&_min1 == &_min2)의 함수는 무엇입니까? (0) | 2022.10.01 |
|---|---|
| 양식을 제출할 때 모든 POST 결과를 인쇄하려면 어떻게 해야 합니까? (0) | 2022.10.01 |
| Jar/war에서 파일을 빠르게 삭제할 수 있는 방법이 있습니까? Jar/war를 추출하여 다시 만들지 않아도 됩니다. (0) | 2022.10.01 |
| InnoDB를 사용한 전문 검색 (0) | 2022.10.01 |
| PHP로 사용자 입력을 삭제하려면 어떻게 해야 합니까? (0) | 2022.10.01 |