Using javadoc for Python documentation [closed]

Answer 1

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.

Answer 2

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

Answer 3

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.

Answer 4

Have a look at the reStructuredText (also known as "reST") format, which is a plaintext/docstring markup format, and probably the most popular in the Python world. And you should certainly look at Sphinx, a tool to generate documentation from reStructuredText (used for eg. the Python documentation itself). Sphinx includes the possibility to extract documentation from the docstrings in your code (see sphinx.ext.autodoc), and recognizes reST field lists following certain conventions. This has probably become (or is becoming) the most popular way to do it.

Your example could look as follows:

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

Or extended with type information:

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