What is the Pythonic way to create informative comments in Python 2.x?

Question

For further clarification, C# has the '///' directive which invokes the super-secret-styled Comments which allow you to have nice comments built into intellisense. Java has the '@' directive that allows you to have nice comments as well.

Does Python have something like this? I hope this question is clear enough, thanks!

Answer 1

They are called docstrings in Python. See the documentation.

A nice feature are the code samples (explained here). They allow to put code in the documentation:

>>> 1 + 1
2
>>>

While this doesn't look like much, there is a tool which can scan the docstrings for such patterns and execute this code as unit tests. This makes sure that Python documenation doesn't go out of date (unlike in other languages).

Answer 2

Python does not have "the" tool for generating documentation. One of the available tools I can recommend is epydoc. It supports directives like @type, @param, @rtype, @returns and @raises. The website also has a few examples.

Answer 3

The convention is well documented in PEP 257.

To summarize, add triple-quoted strings as the first statement in any class or function.

There's also some history that's worth a read if you have time in PEP 256.

Answer 4

In python a docstring can be viewed via commands.

class myClass:
    """
      This is some documentation for the class.
      method1()
      method2()
    """
    def method1(p1):
        ....
        ...
        ...
    def method2():
        ...
        ...

v = myClass

you can then view the docstring by using either

v.__doc__

or

help(myClass)

Answer 5

Hi, as other people has pointed out in Python the resource you are looking for is called doc string. other people has suggested read the documentation, alibeit I suggest watch this link

Sphinx Project, this is an system like Sand Castle that help you building and elaborate documentation, this documentation can be build from doc string but is not mandatory.

hope this helps