Python 문서에 javadoc 사용하기

나는 현재 파이썬으로 시작하고 있으며 강력한 PHP 배경을 가지고 있으며 PHP javadoc에서는 문서 템플릿 으로 사용하는 습관을 들였습니다 .

궁금 해서요 javadoc로 그 자리가 docstring파이썬에서 문서를. 여기서 확립 된 컨벤션 및 / 또는 공식적인 길드 라인은 무엇입니까?

예를 들어 파이썬 마인드에 맞추기에는 너무 정교하거나 가능한 한 간결해야합니까?

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

그리고 내가 너무 철저하다면 대신 이와 같은 것을 사용해야합니까 (대부분의 문서가 __doc__방법을 통해 인쇄되지 않는 경우 )?

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)

일반 텍스트 / docstring 마크 업 형식 인 reStructuredText ( "reST"라고도 함) 형식을 살펴보고 Python 세계에서 가장 널리 사용되는 형식을 살펴보십시오 . 그리고 reStructuredText (예를 들어 Python 문서 자체에서 사용)에서 문서를 생성하는 도구 인 Sphinx를 확실히 살펴 봐야 합니다. Sphinx에는 코드의 문서 문자열에서 문서를 추출 할 수있는 가능성이 포함되어 있으며 ( sphinx.ext.autodoc 참조 ) 특정 규칙에 따라 reST 필드 목록을 인식 합니다 . 이것은 아마도 가장 인기있는 방법이 될 것입니다.

귀하의 예는 다음과 같습니다.

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

또는 유형 정보로 확장 :

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""

Google Python 스타일 가이드를 따르십시오 . Sphinx는 또한 Sphinx 1.3과 함께 제공되는 Napolean 확장을 사용하여이 형식을 구문 분석 할 수 있습니다 ( PEP257 과도 호환 됨 ).

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

위에 링크 된 나폴레옹 문서에서 가져온 예.

모든 유형의 docstring에 대한 포괄적 인 예는 여기에 있습니다 .

파이썬 문서 문자열의 표준은 Python Enhancement Proposal 257에 설명되어 있습니다.

귀하의 방법에 대한 적절한 의견은 다음과 같습니다

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """

" Python 문서의 저자 및 잠재적 저자를 겨냥한" Documenting Python을 살펴보십시오 .

간단히 말해 reStructuredText 는 Python 자체를 문서화하는 데 사용되는 것입니다. 개발자 안내서에는 reST 입문서, 스타일 안내서 및 훌륭한 문서 작성에 대한 일반적인 조언이 포함되어 있습니다.