The ampoule project uses some tags in docstring, like the javadoc ones.
For example from pool.py line 86:
def start(self, ampChild=None):
"""
Starts the ProcessPool with a given child protocol.
@param ampChild: a L{ampoule.child.AMPChild} subclass.
@type ampChild: L{ampoule.child.AMPChild} subclass
"""
What are these tags, which tool uses it.
A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation. Also, it is a common practice to generate online (html) documentation automatically from docstrings.
The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated.
Comments are great for leaving notes for people working on your program. Docstrings provide documentation about functions, classes, and modules. Use docstrings to teach other developers how to use your program.
Just for fun I'll note that the Python standard library is using Sphinx/reStructuredText, whose info field lists are similar.
def start(self, ampChild=None):
"""Starts the ProcessPool with a given child protocol.
:param ampChild: a :class:`ampoule.child.AMPChild` subclass.
:type ampChild: :class:`ampoule.child.AMPChild` subclass
"""
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With