A documentation proposal (non HTML version)

Noel J. Bergman noel at devtech.com
Wed Jan 23 18:20:57 UTC 2002


> As long as the remote comment database would *supplement* comments in the
> base image, then I don't see a problem. But hitting the proposed remote
> comment server should be optional; there are plenty of occasions that I'm
> working on code offline. Code comments should always remain with the code
in
> the image.

It sounds to me as if this database is primarly useful for collecting
comments that can be imported into the image, and tracking which
classes/methods lack comments.  Thus it serves as an aid to identify and
resolve the internal documentation issues within the image.  It is easier
for everyone to view a shared database.

>From that perspective, this database could be populated from existing images
to start the process.  There might be some sort of status flag on the
information, such whether or not the comments have been approved.  Entries
without comments could be flagged in red to highlight the need to comment
them; those with comments that have not been approved could be in orange;
those with approved comments in green.  [Alternatively some visual marker
not dependent upon color could be used]  Along these lines, the earlier
suggestion that the information be tagged for version information makes
sense.

Likewise, I'll bet that Rob would like the presents of SUnit to be flagged.

	--- Noel




More information about the Squeak-dev mailing list