Sử dụng javadoc cho tài liệu Python [đã đóng]

Tôi hiện đang bắt đầu với Python và tôi có một nền tảng PHP mạnh mẽ và trong PHP tôi đã có thói quen sử dụng javadoclàm mẫu tài liệu.

Tôi đã tự hỏi nếu javadoccó vị trí của nó như là docstringtài liệu trong Python. Các công ước được thành lập và / hoặc các bang hội chính thức ở đây là gì?

Ví dụ, một cái gì đó như thế này quá phức tạp để phù hợp với suy nghĩ của Python hoặc tôi nên cố gắng ngắn gọn nhất có thể?

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

Và nếu tôi hơi quá mệt mỏi thì tôi có nên đi bằng thứ gì đó như thế này không (trong đó hầu hết các tài liệu không được in qua __doc__phương thức này)?

# 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)

Có một cái nhìn tại reStructuredText (còn được gọi là "phần còn lại") định dạng, mà là một bản rõ / docstring đánh dấu định dạng, và có lẽ là phổ biến nhất trong thế giới Python. Và bạn chắc chắn nên xem Sphinx , một công cụ để tạo tài liệu từ reSturationuredText (được sử dụng cho ví dụ: chính tài liệu Python). Sphinx bao gồm khả năng trích xuất tài liệu từ các tài liệu trong mã của bạn (xem sphinx.ext.autodoc ) và nhận ra danh sách trường reST theo các quy ước nhất định. Điều này có lẽ đã trở thành (hoặc đang trở thành) cách phổ biến nhất để làm điều đó.

Ví dụ của bạn có thể trông như sau:

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

Hoặc mở rộng với thông tin loại:

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

Làm theo Hướng dẫn về Phong cách Python của Google . Lưu ý rằng Sphinx cũng có thể phân tích định dạng này bằng tiện ích mở rộng Napolean , sẽ được đóng gói với Sphinx 1.3 (điều này cũng tương thích với 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

Ví dụ lấy từ tài liệu Napolean liên kết ở trên.

Một ví dụ toàn diện về tất cả các loại tài liệu ở đây .

Tiêu chuẩn cho chuỗi tài liệu python được mô tả trong Đề xuất nâng cao Python 256 .

Nhận xét thích hợp cho phương pháp của bạn sẽ giống như

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

Hãy xem Tài liệu Python , một trang "nhắm đến các tác giả và tác giả tài liệu tiềm năng cho Python."

Nói tóm lại, reSturationuredText là những gì được sử dụng để ghi lại chính Python. Hướng dẫn của nhà phát triển chứa một mồi reST, hướng dẫn về phong cách và lời khuyên chung để viết tài liệu tốt.