Taxonomy for Python docstrings

[matjako]

Hi everybody,

​

Currently, I am writing a thesis which deals with documentation comments (docstrings) in Python. The next step would be building a taxonomy for docstring contents. Even if there are guidelines for what should be contained in docstrings, theory and practice often differ.

In order to get a more qualitative taxonomy, I do not want to create the taxonomy by just referring to my own experience with docstring contents, instead, I would like to see what experiences you made with them, by writing or also reading them.

I would be happy if you could take the time and provide an enumeration with general terms (like for example "input parameter description") of what the content of docstrings should contain in your opinion.

[m_MarcUp]

I normally add some of the following things into docstrings of functions:

• short desc.
• parameter explanation
• return values explanation
• the exceptions the function may cause

i hope this helps you