Merge lp://staging/~bryce/launchpad/api-docs-fixes-bug into lp://staging/launchpad

Bryce, all-in-all very nice improvements. There are a few potential problems though, resulting from the way interfaces are used in the UI. In Zope (and Launchpad), the same interfaces that are used to define objects can be used for publishing these objects. Many Launchpad forms, for example, use the Description attribute of fields to render the descriptive text next the field (the same goes for Title). The advantage of this approach is that you don't need to describe the same field twice. The disadvantage, is that the title and description you use must be appropriate both for use in the model and for use in the UI. Some of the titles and descriptions you've added might not be appropriate for the UI (the description for tags, for example, that appears on a bug's +edit page). For the same reason, some of the changes you've made are likely to require changes to pagetests, which I think you haven't adjusted yet in this branch. I think that the changes are good in most cases, but let's go once over the visible changes and make sure they work fine, and perhaps also submit this for UI-review.

b.t.w If you find places where you think the description should be different, all hope is not lost - it is still possible to customize the appearance of fields in the UI by changing them in the relevant classes in the the browser package.

Hrm, that's distressing. Is there any way to differentiate between items that only show up on the API docs vs. ones that also show up in the web UI?

Personally, while it seems convenient and time-saving to reuse the web UI strings for the API docs, if the side-effect is making it harder to update the API docs, then it sort of seems like there is a risk that people will be reticent to improve the documentation for the API calls, lest it risk impacting the web UI.

Anyway, if I can find a way to discern which strings are used by the web UI, I can strip out those changes from this branch.

Bryce, with the docstrings you've removed from the diff you can land this branch. Thanks for improving the API documentation, I know for sure that it makes life much better for users.

For the future, I think it's still worth trying to come up with a way to update the documentation for only the API (without affecting the documentation of the interface itself). Perhaps by adding a new decorator, or passing an extra description to the `exported` decorator - that way you'll be able to provide even better documentation to the API which now you must avoid.