A documentation proposal (non HTML version)
rwithers12 at mediaone.net
Thu Jan 24 01:40:52 UTC 2002
At 01:20 PM 1/23/2002, you wrote:
> > 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
> > 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
>Likewise, I'll bet that Rob would like the presents of SUnit to be flagged.
That would certainly be cool. I would be very happy to have them on the
net, somewhere, and be able to LoadTestUnload them. In answering Stef, I
just realized that the exampleFor: constructs can be used to document
interfaces, including exceptions thrown. That is useful information that
Java forces you to specify...but it is there. it's the only useful thing I
find about that language: not that it forces you but that the exceptions
information is there for your consideration. on: Error do: [:ex | ex
return] is *bad* code!
More information about the Squeak-dev