In comments section of PyCharm’s manual there’s a nice hint from developer: #: :type: dict of (str, C) #: :type: list of str It works for me pretty well. Now it makes me wonder what’s the best way to document parametrized classes in Python :).
Good research effort from the Original Poster. It is a surprise that the canonical sphinx documentation does not give a multi-line example on params, despite the fact that multi-line document is inevitable due to the 79-character guideline in PEP8. In practice, considering that your parameter name itself is typically a word or even longer snake_case_words, … Read more
it seems __doc__ is useful to provide some documentation in, say, functions This is true. In addition to functions, documentation can also be provided in modules. So, if you have a file named mymodule.py like this: “””This is the module docstring.””” def f(x): “””This is the function docstring.””” return 2 * x You can access … Read more
There is an official answer, in PEP 257 (the docstring PEP), which is arguably authoritative: The class constructor should be documented in the docstring for its __init__ method. This is quite logical, as this is the usual procedure for functions and methods, and __init__() is not an exception. As a consequence, this puts the code … Read more
One way to do this would be to use a decorator. I’m not sure how I feel about this; I actually searched for commentary on this method and found this answer, which rightly notes that it could mask a design problem. But your use case seems sound to me at first glance. In any case, … Read more
TL;DR raises is used to describe the possible exceptions being raised. raise is recognized by Sphinx when running autodoc and is the same as raises. Full Explanation PyCharm helps in using a few different styles of docstring comments. Three which I often use are: NumPy Format Google Format Sphinx (much more than a format) In … Read more
def my_func(): “””Docstring goes here.””” print my_func.__doc__ This will work as long as you don’t change the object bound to the name my_func. new_func_name = my_func my_func = None new_func_name() # doesn’t print anything because my_func is None and None has no docstring Situations in which you’d do this are rather rare, but they do … Read more
With PyCharm 5.0 we finally got to select Google and NumPy Style Python Docstrings templates. It is also mentioned in the whatsnew section for PyCharm 5.0. How to change the Docstring Format: File –> Settings –> Tools –> Python Integrated Tools There you can choose from the available Docstrings formats: Plain, Epytext, reStructuredText, NumPy, Google … Read more
In Python 3, no wrapper is needed, as the __doc__ attributes of types is writable. from collections import namedtuple Point = namedtuple(‘Point’, ‘x y’) Point.__doc__ = ”’\ A 2-dimensional coordinate x – the abscissa y – the ordinate”’ This closely corresponds to a standard class definition, where the docstring follows the header. class Point(): ”’A … Read more
The docstring is stored in the module’s __doc__ global. print(__doc__) By the way, this goes for any module: import sys; print(sys.__doc__). Docstrings of functions and classes are also in their __doc__ attribute.