<!DOCTYPE qhelp PUBLIC

"-//Semmle//qhelp//EN"

"qhelp.dtd">

<qhelp>

<overview>

<p>PEP8 mandates that all public modules, classes, functions and methods should have a documentation

string. Ensuring that every public module, class, function and method is documented makes it easier

for other developers to maintain the code.

</p>

</overview>

<recommendation>

<p>If a module, class, function or method needs to be public then add a documentation string that

describes the

purpose or use of the object (see PEP 257 for guidelines). If the object does not need to be public

then make it "private" by changing its name from <code>xxx</code> to <code>_xxx</code>.</p>

</recommendation>

<example>

<p>The following simple, public function should be updated to include a documentation string

immediately after the <code>def</code> line.</p>

<sample src="DocStrings.py" />

<p>You might insert the documentation string: <code>"""Return the sum of x and y."""</code> on line 2.

</p></example>

<references>

<li>Python PEP 8: <a href="http://www.python.org/dev/peps/pep-0008/#documentation-strings">Documentation strings</a>.</li>

<li>Python PEP 257: <a href="http://www.python.org/dev/peps/pep-0257">Documentation string conventions

</a>.</li>

</references>

</qhelp>