Using javadoc for Python documentation
Solution 1
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
"""
Solution 2
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.
Solution 3
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 '')
"""
Solution 4
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.
Related videos on Youtube
JF Dion
Software developer - Software engineering Professionnal experience in Java, PHP, JavaScript, TypeScript, HTML, CSS (and related frameworks) Personnal experience in Clojure, Go, Python Interests Software architecture Design patterns Functional programming Event driven Concurrency
Updated on November 28, 2020Comments
-
JF Dion over 3 years
I am currently beginning with Python and I have a strong PHP background and in PHP I have took the habit of using
javadoc
as a documentation template.I was wondering if
javadoc
has its place asdocstring
documentation in Python. What are the established conventions and/or official guildelines here?E.g. is something like this too elaborate to fit in the Python mindset or should I try to be as concise as possible?
""" 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 """
And if I am a bit too exhaustive should I go with something like this instead (where most of the documentation doesn't get printed through the
__doc__
method)?# 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)
-
Alex Dupuy almost 10 yearsThera are also many more answers to this at the earlier question of which this is a duplicate.
-
zvone over 6 yearsPossible duplicate of What is the standard Python docstring format?
-
-
Skylar Saveland almost 12 yearswhat do you do if you need to break a line for a long description? How would that look?
-
Steven almost 12 yearsSee reStructuredText reference, and field lists in particular: docutils.sourceforge.net/docs/ref/rst/…
-
Tadeck almost 11 yearsI have changed that slightly: previously types were referred to as "
string
", while now they are referred to as "str or unicode
". -
vaab almost 11 yearsPEP257 doesn't tell anything on the actual formatting of the argument part. It just states that it should be written, and gives an example. But this is only an example. Therefore, I would definitively advise using the Sphinx convention, as you don't break PEP257 and you use a formatting that could be parsed by sphinx.
-
kratenko almost 10 yearsNote that the way the phrases here do not comply to PEP 257. It should be be
Replace template place holder with values.
instead ofreplaces template place holder with values
- Notice the sentence, upper case letter at start, and full stop (.) at the end. -
Petri almost 10 yearsFrom version 1.3, Sphinx also supports a bit nicer format via the
sphinx.ext.napoleon
extension. -
confused00 over 9 yearsExcept the rst documentation presented above is ugly and has lots of redundant information for humans. I'd rather use a convention that makes my source code pleasant to read without being parsed first
-
Waylon Flinn over 9 yearsfor all the humans out there who read docstrings
-
Oleg Vaskevich almost 9 years@kratenko: I edited the answer to reflect your comment. Thanks!
-
krumpelstiltskin over 8 yearsCould someone please point me to the best documentation specifying these special docstrings like ":param ____:" and ":returns:"? Such a document seems rather hard to find at the moment.
-
radtek about 8 yearsI like this.. flat is better than nested. I just include the type in the param instead of having the type line on its own.
-
confused00 almost 8 yearsUpdated the Google Python Style Guide link
-
Cito over 7 years@confused00 how can I document that my method is returning an array of objects?
-
KRoy about 6 yearsNow I am confused ! args or params ? stackoverflow.com/questions/1788923/parameter-vs-argument
-
user118967 over 4 yearsWhat about links to other classes, methods (in this class and others) and so on? I could not find reStructuredText information detailing this.