Colons at beginning of lines in Python comments

Question

What's the function of the colon : before return here? Is that a style thing in Python?

def close(self):
    """ Close this connection.
    :returns: None
    """
    self.conn.close()
    return

It looks like the kind of thing you see in documentation-oriented markup languages, like Restructured Text, where syntax like that is used to do stuff like make `returns` show up in italics or fixed-width when generating HTML docs from docstrings. I'm not sure which particular documentation-generation library that is from though. — BrenBarn, Sep 06 '17 at 05:15
Agree with @BrenBarn and @chngzm . This is a comment section which was written to be friendly to documentation-generation. Nothing to do with the code structure or python. You can write `"Mary had a :: little :: lamb"` and it would work fine! — kaza, Sep 06 '17 at 05:17
This is not python style. It's just a comment which means the method returns None. — Shiv Shankar, Sep 06 '17 at 05:17

Dewald Abrie · Answer 1 · 2017-09-06T05:22:36.527

Because it is in a docstring (enclosed in triple quotes) it is just like a comment and doesn't do anything other than document your code.

There are various conventions of writing docstrings - this is one of them (the reST format used by Sphinx).

The colons are typically used to describe what parameters the function expects and what the function returns, like so:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

In this case it says that the function is expected to return None.

See this post for more details on the various conventions.

This is the correct answer, it is just a docstring, read the PEP-8 for it [docstring](https://www.python.org/dev/peps/pep-0257/) — death and gravity, Sep 06 '17 at 06:59

score 0 · Answer 2 · answered Sep 06 '17 at 05:17

On some IDEs (namely PyCharm) if you type type triple quotes and then enter below a function signature the IDE will automatically document parameters and return value of the function/method in the style you show. They are called document comments and will allow the IDE to present hover-over information about a parameter/return value when used elsewhere.

This documentation style has no effect on program behavior.

Colons at beginning of lines in Python comments

2 Answers2