How to document fields and properties in Python?

Question

It's easy to document a class or method in Python:

class Something:
  """ Description of the class. """

  def do_it(self):
    """ Description of the method. """
    pass

  class_variable = 1 # How to comment?

  @property
  def give_me_some_special_dict(self):
    """ doesn't work! Doc of general dict will be shown. """
    return {}

But how to document a field or property for usage in API docs or help?

This has been brought forward in the past. In "Abandoned, Withdrawn, and Rejected PEPs": http://www.python.org/dev/peps/pep-0224/ — janislaw, May 19 '11 at 15:16
Possible duplicate of [What is the right way to put a docstring on Python property?](https://stackoverflow.com/questions/16025462/what-is-the-right-way-to-put-a-docstring-on-python-property) — Stevoisiak, Mar 09 '18 at 21:57

score 127 · Accepted Answer · edited Dec 06 '19 at 02:12

127

Python has a PEP (257) that defines Docstring Conventions. Regarding documentation of attributes, it states:

String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".

So the following are considered documented attributes:

class Foo(object):
  velocity = 1  
  """Foo's initial velocity - class variable"""

  def __init__(self, args):
    self.location = 0.0 
    """Foo's initial location - instance variable"""

(Edit: Fixed second docstring)

edited Dec 06 '19 at 02:12

Franklin Yu

8,920
6
43
57

answered May 19 '11 at 15:41

Eli Bendersky

263,248
89
350
412

24

I was wondering too, [and Sphinx does](https://web.archive.org/web/20121017075218/http://sphinx.pocoo.org/ext/autodoc.html). – Jochen Ritzel May 19 '11 at 16:02
3

@Jochen: that's great, since Sphinx is the de-facto tool for Python documentation these days – Eli Bendersky May 19 '11 at 16:19
Here's the PEP ([224](https://www.python.org/dev/peps/pep-0224/)) that talks about attribute docstrings. – Josie Thompson Feb 17 '18 at 22:29
5

Late comment but seems important to me: the standard library `help` function does not display attribute docstrings. – Serge Ballesta Oct 31 '18 at 07:20
6

`help` does not show this documentation for "attribute docstrings" because they're not retained at runtime. According to [PEP 257](https://www.python.org/dev/peps/pep-0257/): "They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to `__doc__`)" – typeracer May 10 '19 at 06:04
5

@JosieThompson PEP 224 was *rejected* back in 2001. PEP 257 is the correct one to refer to. – Franklin Yu Dec 06 '19 at 02:11

score 13 · Answer 2 · answered Aug 27 '13 at 18:35

Documentation of a property in the python interpreter using help works fine for me, see proprerty documentation. Note: IPython's magic help operator, ?, did not display the property docstring.

>>> class foo(object):
>>>    def __init__(self, bar):
>>>        self._bar = bar
>>>    @property
>>>    def bar(self):
>>>        """bar property"""
>>>        return self._bar
>>> help(foo.bar)
Help on property:

    bar property

In Sphinx you must use the :members: directive to document properties, see autodoc documentation. Works like a charm for me!

Attributes will also be documented by Sphinx if :members: is used. Docstrings for attributes can be given as comments preceding the attribute, but using a colon following the hash mark, EG #: the foo attribute. From the Sphinx autodoc documentation:

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.

score 4 · Answer 3 · answered May 19 '11 at 15:15

4

Document freely accessible attributes in the class docstring or make them into properties. You're documenting properties properly, the problem might be in 2.x and old-style classes, which don't support descriptors — inherit from object in that case.

answered May 19 '11 at 15:15

Cat Plus Plus

125,936
27
200
224

score 2 · Answer 4 · answered May 19 '11 at 15:32

With Sphinx notation / Restructured Text in your docstrings you can generate nicely formatted documentation from you Python sources automatically. It also supports arguments and return values for functions - no fields as far as I know, but you can easily create a list for them.

How to document fields and properties in Python?

4 Answers4

Linked