[qmtest] building the documentation via 'python setup.py build_doc'

[Mark Mitchell]

Remember when I said we were picky? :-)

> +def find_file(paths, predicate):
> +    """This function returns the found file (with path) or None if it
> +    wasn't found"""

The way we document all functions is like so:

  """Return a file satisfying 'predicate' from 'paths'.

  'paths' -- A sequence of glob patterns.

  'predicate' -- A callable taking a single string as an argument.

  returns -- The name of the first file matching one of the 'paths'
  and 'predicate'."""

Note that the first sentence is always a single line.  It should have
the form 'Return ...' or something like 'Erase the hard disk.' or 
'Find the answer to the meaning of life.'

Then, each argument is listed, in single quotes, with the "--" bit and a
description.  The type of the argument should usually be mentioned.  The
"returns" bit is similar.  All this makes HappyDoc happy. :-)

Please submit a patch to fix up the docs on all your new functions.

Yes, I know it's a pain, but we're sticklers for documentation.  Zack
says that one of the biggest problems with OpenSource software is
documentation, so we try to be good.

> +class qm_build_doc(build.build):
> +    """This class compiles the QMTest's documentation."""

Grammar: "compiles QMTest's documentation".  The "the" their is
redundant.

> +        # just to be sure this is still valid after chdir()

Start with capital letter, end with period.  Make that change
throughout.  Try to use a complete sentence:

  # Use an absolute path so that calls to chdir do not invalidate
  # the name.

> +class qm_build(build.build):
> +    """The qm_build class extends the build subcommands by 'qm_build_doc'."""

"""Extends 'build' by adding support for building documentation."""

>      """This class overrides the system install_data command. In addition
>      to the original processing, a 'config' module is created that

For classes, too, the first sentence should be on a single line.

More details can follow:

  """A 'QMFoo' is a 'Foo' with an extra 'Bar'.

  The 'Bar' is set ... It is used ..."""

Thanks!

-- 
Mark Mitchell
CodeSourcery, LLC
mark at codesourcery.com