A documentation proposal (non HTML version)

Rob Withers 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
>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.

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!

Rob




More information about the Squeak-dev mailing list