Needs to give better error messages when docstrings are mis-formatted

[Steve Kowalik]

AssertionError: Invalid docstring Derive a distroseries from this one.

This method performs checks, can create the new distroseries if
necessary, and then creates a job to populate the new
distroseries.

:param name: The name of the new distroseries we will create if it
doesn't exist, or the name of the distroseries we will look up, and
then initialise.
:param displayname: The Display Name for the new distroseries. If the
distroseries already exists this parameter is ignored.
:param summary: The Summary for the new distroseries. If the
distroseries already exists this parameter is ignored.
:param description: The Description for the new distroseries. If the
distroseries already exists this parameter is ignored.
:param version: The version for the new distroseries. If the
distroseries already exists this parameter is ignored.
:param distribution: The distribution the derived series will belong
to. If it isn't specified this distroseries' distribution is used.
:param state: The state the new distroseries will be created in.
If the distroseries isn't specified, this parameter will be ignored.
Defaults to FROZEN.
:param arches: The architectures to copy to the derived series. If not
specified, all of the arches are copied.
:param packagesets: The packagesets to copy to the derived series. If
not specified, all of the packagesets are copied.
:return: The ID of the job created.:
 Line 9: Field list ends without a blank line; unexpected unindent.
make: *** [lib/canonical/launchpad/apidoc/index.html] Error 1

This is not a very helpful error message, and you can only really fix it if you know that what is what lazr-restful is explicitly looking for.

[Gary Poster (gary)]

Hi Steve. Could you clarify this a bit more? It looks like the error is so unhelpful that I don't know what you are talking about.

I think this is about Launchpad making the apidoc, as opposed to lazr.restful itself, yes?

Clear instructions to dupe would be especially helpful. If you've already figured out root causes, identifying pertinent modules and classes would be very nice too, but if not, knowing how to dupe should be sufficient. :-)

Gary