[Tutor] Multi-line comments?

[John Fouhy]

On 07/06/07, Brad Tompkins <bradleytompkins at gmail.com> wrote:
> Is there a way to make use of multi-line comments when programming using
> python?  Having to stick a # in front of every line gets pretty tedious when
> I want to make a comment more detailed than I normally would.
>
> If there isn't a way, can someone recommend a text editor (I know emacs and
> probably vi can do this, but they seem difficult to use) that will comment
> out blocks of text automatically for me?

With emacs, you can highlight a region and choose "Comment out region"
from the menu bar.  With vi, to comment out the current line and the
next n, type   :,+ns/^/#/

But the real answer to your question is to use docstrings.  A
docstring is a multiline string (delimited by """ """) at the start of
a block of code.  A typical python module might look like this:

--- foo.py ---
""" Module for working with foos.

This module adds foo support to python.
etc.
"""

class Foo(object):
   """ Main foo class.

   More stuff.
   """

   def useBar(self, bar):
      """ Apply this foo to a bar. """
-------

Python's help system can then pick up the docstrings automatically.
eg, if I started the interpreter and typed 'import Foo', then
'help(Foo)' would give me the module docstring, 'help(Foo.Foo)' would
give me the class docstring, and so on.

Check out the source code for python modules on your system (in the
lib directory of your install) for lots of examples.

-- 
John.