매개 변수를 사용하여 메서드를 문서화하려면 어떻게 해야 합니까?
Python의 문서 문자열을 사용하여 매개 변수를 사용하여 메서드를 문서화하는 방법은 무엇입니까?
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
...
이것이 대부분의 Python 개발자들이 사용하는 규약입니까?
Keyword arguments:
<parameter name> -- Definition (default value if any)
좀 더 격식을 차릴 줄 알았는데
def complex(real=0.0, imag=0.0):
"""Form a complex number.
@param: real The real part (default 0.0)
@param: imag The imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
환경: Python 2.7.1
docstring은 자유 형식이기 때문에 API 문서를 생성하기 위해 코드를 해석하기 위해 무엇을 사용하는지에 따라 달라집니다.
Sphinx 마크업은 널리 사용되고 있으며 Python 프로젝트를 문서화하는 데 있어 디커버링 표준이 되고 있기 때문에 나는 Sphinx 마크업에 익숙해지는 것을 추천한다.부분적으로는 훌륭한 readthedocs.org 서비스 때문이다.Sphinx 설명서의 예를 Python 스니펫으로 바꾸려면:
def send_message(sender, recipient, message_body, priority=1) -> int:
"""
Send a message to a recipient.
:param str sender: The person sending the message
:param str recipient: The recipient of the message
:param str message_body: The body of the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring
"""
이 마크업은 문서와 기타 문서 간의 상호 참조를 지원합니다.스핑크스의 매뉴얼에서는 (예::py:attr:
그 대신,:attr:
소스코드에서 문서화할 때 사용합니다.
당연히 API를 문서화하는 다른 툴도 있습니다.더 고전적인 독시겐이 있는데\param
명령어는 Sphinx처럼 Python 코드를 문서화하기 위해 특별히 설계되지 않았습니다.
지금까지의 경험에 비추어 볼 때, Numpy docstring 규칙(PEP257 superset)은 스핑크스와 같은 툴에서도 지원되는 가장 광범위한 규칙입니다.
한 가지 예:
Parameters
----------
x : type
Description of parameter `x`.
표기법:
도구:
- Epydoc: Python용 자동 API 문서 생성
- sphinx.ext를 클릭합니다.autodoc – 문서 문자열 문서 포함
- PyCharm은 문서스트링에 대한 훌륭한 지원을 제공합니다.
업데이트: Python 3.5에서 기계에서 읽을 수 있는 컴팩트한 구문인 type hints를 사용할 수 있습니다.
from typing import Dict, Union
def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
"""
Explanation: this function takes two arguments: `i` and `d`.
`i` is annotated simply as `int`. `d` is a dictionary with `str` keys
and values that can be either `str` or `int`.
The return type is `int`.
"""
이 구문의 주요 장점은 언어에 의해 정의되고 모호하지 않기 때문에 PyCharm과 같은 툴이 쉽게 이용할 수 있다는 것입니다.
python doc 문자열은 자유 형식이므로 원하는 방식으로 문서화할 수 있습니다.
예:
def mymethod(self, foo, bars):
"""
Does neat stuff!
Parameters:
foo - a foo of type FooType to bar with.
bars - The list of bars
"""
몇 가지 관례가 있지만 비단뱀은 그 어느 것도 강요하지 않습니다.일부 프로젝트에는 고유한 규칙이 있습니다.docstring을 사용하기 위한 일부 도구도 특정 규칙을 따릅니다.
스핑크스를 사용하여 코드를 문서화할 계획이라면 파라미터에 적합한 형식의 HTML 문서를 '서명' 기능으로 생성할 수 있습니다.http://sphinx-doc.org/domains.html#signatures
여기의 다른 답변에서 이미 지적한 바와 같이, 아마도 스핑크스를 사용하여 나중에 멋진 문서를 생성할 수 있도록 스핑크스를 사용하는 것이 주류입니다.
그래서 저는 개인적으로 가끔 인라인 댓글 스타일로 갑니다.
def complex( # Form a complex number
real=0.0, # the real part (default 0.0)
imag=0.0 # the imaginary part (default 0.0)
): # Returns a complex number.
"""Form a complex number.
I may still use the mainstream docstring notation,
if I foresee a need to use some other tools
to generate an HTML online doc later
"""
if imag == 0.0 and real == 0.0:
return complex_zero
other_code()
다음은 인라인에 기재된 몇 가지 세부사항을 포함한 다른 예입니다.
def foo( # Note that how I use the parenthesis rather than backslash "\"
# to natually break the function definition into multiple lines.
a_very_long_parameter_name,
# The "inline" text does not really have to be at same line,
# when your parameter name is very long.
# Besides, you can use this way to have multiple lines doc too.
# The one extra level indentation here natually matches the
# original Python indentation style.
#
# This parameter represents blah blah
# blah blah
# blah blah
param_b, # Some description about parameter B.
# Some more description about parameter B.
# As you probably noticed, the vertical alignment of pound sign
# is less a concern IMHO, as long as your docs are intuitively
# readable.
last_param, # As a side note, you can use an optional comma for
# your last parameter, as you can do in multi-line list
# or dict declaration.
): # So this ending parenthesis occupying its own line provides a
# perfect chance to use inline doc to document the return value,
# despite of its unhappy face appearance. :)
pass
(@mark-horvath가 다른 코멘트에서 이미 지적한 바와 같이) 이점은 다음과 같습니다.
- 가장 중요한 것은 파라미터와 그 문서는 항상 함께 유지되기 때문에 다음과 같은 이점이 있습니다.
- 입력이 적음(변수 이름을 반복할 필요 없음)
- 변수 변경/삭제 시 유지보수가 용이함일부 매개 변수 이름을 바꾼 후에는 분리된 매개 변수 문서 단락이 없습니다.
- 누락된 코멘트를 쉽게 찾을 수 있습니다.
어떤 사람들은 이 스타일이 "못생겼다"고 생각할지도 모른다.하지만 '못생겼다'는 건 주관적인 단어죠좀 더 중립적인 방법은 이 스타일이 주류가 아니기 때문에 당신에게는 덜 친숙해 보일 수 있기 때문에 덜 편안하다고 말하는 것이다.'편안함'은 주관적인 단어이기도 하다.하지만 요점은 위에서 설명한 모든 이점이 객관적이라는 것입니다.표준적인 방법으로는 그것들을 달성할 수 없다.
언젠가는 이러한 인라인 스타일을 사용할 수 있는 문서 생성 툴이 등장할 것입니다.그것이 입양을 촉진할 것이다.
추신: 이 답변은 적절하다고 생각될 때마다 인라인 코멘트를 사용하는 것을 선호하기 때문에 도출되었습니다.사전 문서 작성에도 같은 인라인 스타일을 사용합니다.
파라미터의 유형을 문서화하는 보다 구조화된 방법을 제공하는 유형별 답변(https://stackoverflow.com/a/9195565/2418922),)을 기반으로 파라미터의 유형과 설명을 모두 문서화하는 구조화된 방법도 있습니다.
def copy_net(
infile: (str, 'The name of the file to send'),
host: (str, 'The host to send the file to'),
port: (int, 'The port to connect to')):
pass
예: https://pypi.org/project/autocommand/
문서 문자열은 Python 쉘과 같은 대화형 환경에서만 유용합니다.인터랙티브하게 사용되지 않는 오브젝트(내부 오브젝트, 프레임워크콜백 등)를 문서화할 때는 통상의 코멘트를 사용하는 것이 좋습니다.다음은 항목에서 들여쓰기된 코멘트를 각각 줄에 걸 때 사용하는 스타일입니다.그러면 코멘트가 다음 항목에 적용되는 것을 알 수 있습니다.
def Recomputate \
(
TheRotaryGyrator,
# the rotary gyrator to operate on
Computrons,
# the computrons to perform the recomputation with
Forthwith,
# whether to recomputate forthwith or at one's leisure
) :
# recomputates the specified rotary gyrator with
# the desired computrons.
...
#end Recomputate
이런 종류의 일은 문서스트링으로는 할 수 없다.
언급URL : https://stackoverflow.com/questions/9195455/how-to-document-a-method-with-parameters
'programing' 카테고리의 다른 글
JavaScript를 사용하여 CSS 값 가져오기 (0) | 2022.10.10 |
---|---|
IntelliJ가 선언을 찾을 수 없습니다. (0) | 2022.10.10 |
jQuery에서 div 요소 만들기 (0) | 2022.10.10 |
jQuery: jQuery에서 숨겨진 요소의 높이를 가져옵니다. (0) | 2022.10.10 |
Python 목록 감산 작업 (0) | 2022.10.10 |