I have seen a few different styles of writing docstrings in Python, what are the most popular styles?

What are the most common Python docstring formats?

Is there a mechanism to comment out large blocks of Python code?

Right now, the only ways I can see of commenting out code are to either start every line with a `#`, or to enclose the code in triple quotes: `&quot;&quot;&quot;`.

The problem with these is that inserting `#` before every line is cumbersome and `&quot;&quot;&quot;` makes the string I want to use as a comment show up in generated documentation.

After reading all comments, the answer seems to be &quot;No&quot;.


How to comment out a block of code in Python

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 as `docstring` 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?

    &quot;&quot;&quot;
    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
    &quot;&quot;&quot;

And if I am a bit too exhaustive should I go with something like this instead (where most of the documentation doesn&#39;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 = &#39;&#39;, priority = &#39;&#39;, priority_name = &#39;&#39;, message = &#39;&#39;):
        &quot;&quot;&quot;
        replaces template place holder with values
        &quot;&quot;&quot;
        values = {&#39;%timestamp%&#39; : timestamp,
                  &#39;%priorityName%&#39; : priority_name,
                  &#39;%priority%&#39; : priority,
                  &#39;%message%&#39; : message}
        
        return self.__pattern.format(**values)


Using javadoc for Python documentation

Pylint throws errors that some of the files are missing docstrings. I try and add docstrings to each class, method and function, but it seems that Pylint also checks that files should have a docstring at the beginning of them. Can I disable this somehow?

I would like to be notified of a docstring is missing inside a class, function or method, but it shouldn&#39;t be mandatory for a file to have a docstring.

(Is there a term for the legal jargon often found at the beginning of a proprietary source file? Any examples? I don&#39;t know whether it is a okay to post such a trivial question separately.)


How do I disable &quot;missing docstring&quot; warnings at a file-level in Pylint?

I&#39;m writing a lightweight class whose attributes are intended to be publicly accessible, and only sometimes overridden in specific instantiations.  There&#39;s no provision in the Python language for creating docstrings for class attributes, or any sort of attributes, for that matter.  What is the expected and supported way, should there be one, to document these attributes?  Currently I&#39;m doing this sort of thing:

    class Albatross(object):
        &quot;&quot;&quot;A bird with a flight speed exceeding that of an unladen swallow.

        Attributes:
        &quot;&quot;&quot;
    
        flight_speed = 691
        __doc__ += &quot;&quot;&quot;
            flight_speed (691)
              The maximum speed that such a bird can attain.
        &quot;&quot;&quot;
    
        nesting_grounds = &quot;Raymond Luxury-Yacht&quot;
        __doc__ += &quot;&quot;&quot;
            nesting_grounds (&quot;Raymond Luxury-Yacht&quot;)
              The locale where these birds congregate to reproduce.
        &quot;&quot;&quot;
    
        def __init__(self, **keyargs):
            &quot;&quot;&quot;Initialize the Albatross from the keyword arguments.&quot;&quot;&quot;
            self.__dict__.update(keyargs)

This will result in the class&#39;s docstring containing the initial standard docstring section, as well as the lines added for each attribute via augmented assignment to `__doc__`.

Although this style doesn&#39;t seem to be expressly forbidden in the [docstring style guidelines][1], it&#39;s also not mentioned as an option.  The advantage here is that it provides a way to document attributes alongside their definitions, while still creating a presentable class docstring, and avoiding having to write comments that reiterate the information from the docstring.  I&#39;m still kind of annoyed that I have to actually write the attributes twice; I&#39;m considering using the string representations of the values in the docstring to at least avoid duplication of the default values.

Is this a heinous breach of the ad hoc community conventions?  Is it okay?  Is there a better way?  For example, it&#39;s possible to create a dictionary containing values and docstrings for the attributes and then add the contents to the class `__dict__` and docstring towards the end of the class declaration; this would alleviate the need to type the attribute names and values twice.  **edit**: this last idea is, I think, not actually possible, at least not without dynamically building the entire class from data, which seems like a really bad idea unless there&#39;s some other reason to do that.

I&#39;m pretty new to python and still working out the details of coding style, so unrelated critiques are also welcome.


  [1]: http://www.python.org/dev/peps/pep-0257/

How to document class attributes in Python?

I like Doxygen to create documentation of C or PHP code. I have an upcoming Python project and I think I remember that Python doesn&#39;t have `/* .. */` comments, and also has its own self-documentation facility which seems to be the pythonic way to document.

Since I&#39;m familiar with Doxygen, how can I use it to produce my Python documentation? Is there anything in particular that I need to be aware of?

How to document Python code using Doxygen

I have a Python script with a docstring. When the parsing of the command-line arguments does not succeed, I want to print the docstring for the user&#39;s information.

Is there any way to do this?

## Minimal example

    #!/usr/bin/env python
    &quot;&quot;&quot;
    Usage: script.py

    This describes the script.
    &quot;&quot;&quot;

    import sys


    if len(sys.argv) &lt; 2:
        print(&quot;&lt;here comes the docstring&gt;&quot;)



How can I print a Python file&#39;s docstring when executing it?

Is it possible to add a documentation string to a namedtuple in an easy manner?

I tried

    from collections import namedtuple

    Point = namedtuple(&quot;Point&quot;, [&quot;x&quot;, &quot;y&quot;])
    &quot;&quot;&quot;
    A point in 2D space
    &quot;&quot;&quot;

    # Yet another test

    &quot;&quot;&quot;
    A(nother) point in 2D space
    &quot;&quot;&quot;
    Point2 = namedtuple(&quot;Point2&quot;, [&quot;x&quot;, &quot;y&quot;])

    print Point.__doc__ # -&gt; &quot;Point(x, y)&quot;
    print Point2.__doc__ # -&gt; &quot;Point2(x, y)&quot;

but that doesn&#39;t cut it. Is it possible to do in some other way?

Adding docstrings to namedtuples?

Does PyCharm 2.7 (or will PyCharm 3) have support for custom docstring and doctest stubs?  If so, how does one go about writing this specific type of custom extension?

My current project has standardized on using the Google Python Style Guide (http://google-styleguide.googlecode.com/svn/trunk/pyguide.html).  I love PyCharm&#39;s docstring support, but it&#39;s only two supported formats right now are epytext and reStructureText.  I want, and am willing to write myself, a PyCharm plugin that creates a documentation comment stub formatted in either Google or Numpydoc style (https://pypi.python.org/pypi/sphinxcontrib-napoleon/). Of special importance here is incorporating the type inference abilities that PyCharm has with the other two documentation types.

Custom PyCharm docstring stubs (i.e. for google docstring or numpydoc formats)

I want to print the docstring of a python function from inside the function itself.
for eg.

    def my_function(self):
      &quot;&quot;&quot;Doc string for my function.&quot;&quot;&quot;
      # print the Docstring here.

At the moment I am doing this directly after `my_function` has been defined.

    print my_function.__doc__

But would rather let the function do this itself.

I have tried calling `print self.__doc__` `print self.my_function.__doc__` and `print this.__doc__` inside my_function but this did not work.

How to print Docstring of python function from inside the function itself?

So I&#39;m trying to create a &quot;dynamic&quot; docstring which is something like this:

    ANIMAL_TYPES = [&quot;mammals&quot;, &quot;reptiles&quot;, &quot;other&quot;]
    
    def func(animalType):
    &quot;&quot;&quot; This is a sample function.
    
        @param animalType: &quot;It takes one of these animal types %s&quot; % ANIMAL_TYPES
    &quot;&quot;&quot;

to basically let the docstring for `@param animalType` show whatever `ANIMAL_TYPES` has; so that when this variable is updated, the docstring will be updated automatically. 

Unfortunately, it doesn&#39;t seem to work. Does anyone know if there is a way of achieving this?

How to put a variable into Python docstring

I use the PyCharm IDE which assists with crafting PEP0257-compliant docstrings. It provides two attributes I don&#39;t entirely understand the distinction/use between:

 - `:raise Exception: exception explanation here`
 - `:raises Exception: exception explanation here`

When would I use `raise` as opposes to `raises` in my docstring? Specifically, if a class required an argument that was not provided and raises a `TypeError`, which should be used to document that?

Python Docstring: raise vs. raises

I can&#39;t figure out what does the `print(__doc__)` do at the beginning of a script, like [in this Scikit example][1].

I have been looking for **Python docstrings** in google, and it seems `__doc__` is useful to provide some documentation in, say, functions. But I can&#39;t see what does `__doc__` do in the middle of a script.


  [1]: http://scikit-learn.org/stable/auto_examples/classification/plot_digits_classification.html#example-classification-plot-digits-classification-py 

print(__doc__) in Python 3 script

I did not find any best practice about what should be documented in the classes and `__init__` docstrings. Sometimes I find that the constructor arguments are already documented in the classes docstring, sometimes the are described in the `__init__` docstring. I prefer describing the construction within the classes docstring, as this is what you call when creating a new instance. But what should be documented in the `__init__` methods docstring then?

***********
_edit:_

I know about the [google styleguide][1] and the [google docstring style example][2], but both do not answer my question. The docstring style example does say 

&gt; The `__init__` method may be documented in either the class level
        docstring, or as a docstring on the `__init__` method itself.
Either form is acceptable, but the two should not be mixed. Choose one
        convention to document the `__init__` method and be consistent with it.

But if I choose to put the docstring of the `__init__` function into the class level docstring, what should the `__init__` docstring contain?

  [1]: https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments
  [2]: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

Is there a consensus what should be documented in the classes and __init__ docstrings?

I really like using docstrings in Python to specify type parameters when projects get beyond a certain size.

I&#39;m having trouble finding a standard to use to specify that a parameter is a list of specific objects, e.g. in Haskell types I&#39;d use [String] or [A].

Current standard (recognisable by PyCharm editor):

    def stringify(listOfObjects):
        &quot;&quot;&quot;
        :type listOfObjects: list
        &quot;&quot;&quot;
        return &quot;, &quot;.join(map(str, listOfObjects))

What I&#39;d prefer:

**OPTION 1**

    def stringify(listOfObjects):
        &quot;&quot;&quot;
        :type listOfObjects: list&lt;Object&gt;  
        &quot;&quot;&quot;
        return &quot;, &quot;.join(map(str, listOfObjects))

**OPTION 2**

    def stringify(listOfObjects):
        &quot;&quot;&quot;
        :type listOfObjects: [Object]
        &quot;&quot;&quot;
        return &quot;, &quot;.join(map(str, listOfObjects))

I suppose that wasn&#39;t a great example - the more relevant use case would be one where the objects in the list must be of a specific type.

**BETTER EXAMPLE**

    class Food(Object):
        def __init__(self, calories):
            self.calories = calories

    class Apple(Food):
        def __init__(self):
            super(self, 200)

    class Person(Object):
        energy = 0
        def eat(foods):
            &quot;&quot;&quot;
            :type foods: [Food]  # is NOT recognised by editor
            &quot;&quot;&quot;
            for food in foods:
                energy += food.calories

So, other than the fact that I&#39;m getting hungry, this example illustrates that if called with a list of the wrong kind of object, the code would break. Hence the importance of documenting not only that it needs a list, but that it needs a list of Food.

**RELATED QUESTION**
https://stackoverflow.com/questions/6318814/how-can-i-tell-pycharm-what-type-a-parameter-is-expected-to-be
Please note that I&#39;m looking for a more specific answer than the one above.


How to specify that a parameter is a list of specific objects in Python docstrings

I have a problem using docstrings with decorators. Given the following example:

    def decorator(f):
        def _decorator():
            print &#39;decorator active&#39;
            f()
        return _decorator
    
    @decorator
    def foo():
        &#39;&#39;&#39;the magic foo function&#39;&#39;&#39;
        print &#39;this is function foo&#39;
    
    help(foo)

Now the help doesn&#39;t show me the docstring of `foo` as expected, it shows:

    Help on function _decorator in module __main__:
    
    _decorator()

Without the decorator, the help is correct:

    Help on function foo in module __main__:
    
    foo()
        the magic foo function

 I know, that the function `foo` is wrapped by the decorator, and so the function object is not the function `foo` any more. But what is a nice solution to get the docstring (and the help) as expected?

Python decorator handling docstrings

I have a wrapper function that returns a function. Is there a way to programmatically set the docstring of the returned function? If I could write to `__doc__` I&#39;d do the following:

    def wrapper(a):
        def add_something(b):
           return a + b
        add_something.__doc__ = &#39;Adds &#39; + str(a) + &#39; to `b`&#39;
        return add_something

Then I could do

    &gt;&gt;&gt; add_three = wrapper(3)
    &gt;&gt;&gt; add_three.__doc__
    &#39;Adds 3 to `b`

However, since `__doc__` is read-only, I can&#39;t do that. What&#39;s the correct way?

------

Edit: Ok, I wanted to keep this simple, but of course this is not what I&#39;m actually trying to do. Even though in general `__doc__` is writeable in my case it isn&#39;t.

I am trying to create testcases for `unittest` automatically. I have a wrapper function that creates a class object that is a subclass of `unittest.TestCase`:

    import unittest
    def makeTestCase(filename, my_func):
        class ATest(unittest.TestCase):
            def testSomething(self):
                # Running test in here with data in filename and function my_func
                data  = loadmat(filename)
                result = my_func(data)
                self.assertTrue(result &gt; 0)
                                
        return ATest

If I create this class and try to set the docstring of `testSomething` I get an error:
    
    &gt;&gt;&gt; def my_func(): pass
    &gt;&gt;&gt; MyTest = makeTestCase(&#39;some_filename&#39;, my_func)
    &gt;&gt;&gt; MyTest.testSomething.__doc__ = &#39;This should be my docstring&#39;
    AttributeError: attribute &#39;__doc__&#39; of &#39;instancemethod&#39; objects is not writable


How do I programmatically set the docstring?

So, reStructuredText is
[the recommended way](https://www.python.org/dev/peps/pep-0287) for Python code
documentation, if you try hard enough, you can
[find in the sphinx documentation](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-signatures)
how to normalize your function signature documentation. All given examples are
single-line, but what if a parameter description is multi-line like the following
?

    def f(a, b):
        &quot;&quot;&quot; Does something with a and b

        :param a: something simple
        :param b: well, it&#39;s not something simple, so it may require more than eighty
                  chars
        &quot;&quot;&quot;

What is the syntax/convention for that ? Should I indent or not ? will it break reSTructuredText rendering ?


Multi-line description of a parameter description in python docstring

I have an OO hierarchy with docstrings that take as much maintenance as the code itself. E.g.,

    class Swallow(object):
        def airspeed(self):
            &quot;&quot;&quot;Returns the airspeed (unladen)&quot;&quot;&quot;
            raise NotImplementedError

    class AfricanSwallow(Swallow):
        def airspeed(self):
            # whatever

Now, the problem is that `AfricanSwallow.airspeed` does not inherit the superclass method&#39;s docstring. I know I can keep the docstring using the template method pattern, i.e.

    class Swallow(object):
        def airspeed(self):
            &quot;&quot;&quot;Returns the airspeed (unladen)&quot;&quot;&quot;
            return self._ask_arthur()

and implementing `_ask_arthur` in each subclass. However, I was wondering whether there&#39;s another way to have docstrings be inherited, perhaps some decorator that I hadn&#39;t discovered yet?

Inheriting methods&#39; docstrings in Python

I&#39;m starting an open source Python project shortly and I&#39;m trying to decide in advance how to write my docstrings. The obvious answer would be using reStructuredText and Sphinx with `autodoc`, because I *really* like the idea of simply properly documenting my code in my docstrings then have Sphinx automatically construct an API doc for me.

The problem is the reStructuredText syntax it uses - I think it&#39;s completely unreadable before it&#39;s rendered. For instance:


	:param path: The path of the file to wrap
	:type path: str
	:param field_storage: The :class:`FileStorage` instance to wrap
	:type field_storage: FileStorage
	:param temporary: Whether or not to delete the file when the File instance
		is destructed
	:type temporary: bool

You have to *really* slow down and take a minute to make any sense out of that syntactic jumble. I like much more the Google way ([Google Python Style Guide][1]), which counterpart to the above looks like this:

&lt;pre&gt;
Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The FileStorage instance to wrap
    temporary (bool): Whether or not to delete the file when the File
        instance is destructed
&lt;/pre&gt;

**Way** nicer! But of course, Sphinx will have none of that and renders all the text after `Args:` in one long line.

So to summarize - before I go and defile my code base with this reStructuredText syntax I would like to know if there are any real alternatives to using it and Sphinx, short of just writing my own API doc. For instance, is there an extension for Sphinx that handles Google Style Guide&#39;s docstring style?

  [1]: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html

All Docstring Solutions on Gang of Coders

Total of 20 Docstring Solutions