I'm just trying to get a better feel for the layout of Python docstrings (Between the """ """)
I've seen docstrings with different layouts...such as...
"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign
:DESCRIPTION:
Tags with colons
DESCRIPTION
And tags with nothing
"""
Do any of these have functional action? Is the @ associated with Elixir? Or are these just preferences amongst developers? I've looked through the style guide for docstrings, but can't see where it addresses such things...
Thanks!
Python docstrings can be written following several formats:
Historically a javadoc like style was prevalent. It was used by Epydoc (with the called Epytext format) to generate documentation.
Example:
"""
This is a javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation.
Example:
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
Google has his own format that is quite used. It also can be interpreted by Sphinx. Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.
Example:
"""
This is a groups style docs.
Parameters:
param1 - this is the first param
param2 - this is a second param
Returns:
This is a description of what is returned
Raises:
KeyError - raises an exception
"""
It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.
Note: The examples are taken from the Pyment documentation. You can see this tuto for more informations about docstrings.