How to document a method with parameters?

Question

How to document methods with parameters using Python documentation lines?

EDIT: PEP 257 gives this example:

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

Is this convention used by most Python developers?

 Keyword arguments: <parameter name> -- Definition (default value if any) 

I was expecting something more formal, such as

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

Environment : Python 2.7.1

Answer 1

Based on my experience, conditional document agreements (PEP257 superset) are the most common agreements that are also supported by tools like Sphinx .

One example:

 Parameters ---------- x : type Description of parameter 'x'. 

Answer 2

Since the documentation strings are arbitrary, it really depends on what you use to analyze the code to create the API documentation.

I would recommend familiarizing yourself with Sphinx markup , as it is widely used and becomes the de facto standard for documenting Python projects, in part because of the excellent readthedocs.org service. To paraphrase an example from the Sphinx documentation as a Python snippet:

 def send_message(sender, recipient, message_body, priority=1): ''' 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 ''' 

This markup supports cross-referencing between documents and more. Note that the Sphinx documentation uses (for example) :py:attr: whereas you can just use :attr: when documenting from source code.

Naturally, there are other tools for documenting the API. There is a more classic Doxygen that uses \param commands, but they are not specifically designed to document Python code like Sphinx.

Please note that there is a similar question with a similar answer here ...

Answer 3

Legend:

• Poc 257 Docstring Agreements
• PEP 287 reStructuredText Docstring Format

Instruments:

• Epydoc: automatically generate API documentation for Python
• sphinx.ext.autodoc - Include documentation from docstrings
• PyCharm has good support for docstrings

---

Update. Starting with Python 3.5, you can use the hint type , which is a compact, machine-readable syntax:

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

The main advantage of this syntax is that it is language-specific and unambiguous, so tools like PyCharm can easily use it.

Answer 4

python doc strings are free form , you can document them in any way.

Examples:

 def mymethod(self, foo, bars): """ Does neat stuff! Parameters: foo - a foo of type FooType to bar with. bars - The list of bars """ 

Now there are some conventions, but python does not apply any of them. Some projects have their own agreements. Some docstrings tools also follow certain conventions.

Answer 5

If you plan to use Sphinx to document your code, it is able to create well-formatted HTML documents for your parameters with their "signature" function. http://sphinx-doc.org/domains.html#signatures

Answer 6

The main thread, as already mentioned in other answers, probably follows the Sphinx path so you can use Sphinx to create these unusual documents later.

At the same time, I personally sometimes use the built-in style of comments.

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

Another example here, with some tiny details documented in a line:

 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 

Benefits (as @ mark-horvath already mentioned in another comment):

• Most importantly, the parameters and their document always remain together, which gives the following advantages:
• Less input (no need to repeat the variable name)
• Easier maintenance when changing / deleting a variable. After renaming a parameter, there will never be a paragraph with a parameter document.
• and easier to find a missing comment.

Now, some might think that this style looks ugly. But I would say ugly is a subjective word. A more neutral way is to say that this style is not mainstream, so it may seem less familiar to you and therefore less convenient. Again, “convenient” is also a subjective word. But the fact is that all the advantages described above are objective. You cannot reach them if you follow the standard path.

We hope that someday in the future there will be a tool for generating documents that can also use such a built-in style. This will encourage adoption.

PS: This answer stems from my own preference for using inline comments whenever I see fit. I use the same inline style to document the dictionary too.

Answer 7

Dockers are used only in interactive environments, for example. Python shells. When documenting objects that will not be used interactively (for example, internal objects, structure callbacks), you can also use regular comments. Heres the style that I use to hang indented comments from elements, each on its own line, so you know what the comment applies to:

 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 leisure ) : # recomputates the specified rotary gyrator with # the desired computrons. ... #end Recomputate 

You cannot do such things with dockstories.