On 21.04.2010, at 10:29, Michael Haupt wrote:
> 
> Class comment changes will have to be "released" in the form of Inbox
> or Trunk uploads right now, right? I don't think this is a very good
> thing. While documentation should always evolve along the code it is
> intended to document, it should not be necessary to update the *code*
> package when only the *documentation* changes.

IMHO the code is exactly where the documentation belongs. Sure, make external editors and even formats or databases or whatever if that is more convenient. But the authoritative version should be the one in the image. It's not official unless committed.

> In my opinion, a packageable documentation format is very important.
> That also makes documentation kind of optional in an image - and
> production images could be shipped (or production software installed)
> without the documentation.

I agree that the documentation should be removable from the image. But in production you wouldn't ship the sources anyway. Comments are only in the source files, not the image. And if methods are used to store documentation literally, those could be removed when deploying. 

But the primary documentation should be internal. External documentation should be generated from the image, not the other way around.

- Bert -