Programing

Python 문서에 javadoc 사용하기

lottogame 2020. 6. 5. 08:02
반응형

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
"""

Follow Google Python Style Guide. Note that Sphinx can also parse this format using the Napolean extension, which will come packaged with Sphinx 1.3 (this is also compatible with 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

Example taken from the Napolean documentation linked above.

A comprehensive example on all types of docstrings here.


The standard for python documentation strings is described in Python Enhancement Proposal 257.

The appropriate comment for your method would be something like

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 '')
    """

Take a look at Documenting Python, a page "aimed at authors and potential authors of documentation for Python."

In short, reStructuredText is what's used for documenting Python itself. The developer's guide contains a reST primer, style guide, and general advice for writing good documentation.

참고URL : https://stackoverflow.com/questions/5334531/using-javadoc-for-python-documentation

반응형