> "Jason Voegele" <jason / jvoegele.com> writes:
> 
>> I agree that the simple @tags are better than XML style tags.  I'm not
>> sure  the @ symbol is the one we want, though.  Say, for example that
>> your Book  class has an instance variable named @author that you
>> reference in one of  your doc-comments.  This could confuse the doc
>> tool.  How 'bout %param?
>> 
>> ##
>> # A class all about books.
>> #
>> # %author Jason Voegele
>> # %version 1.0
> 
> In the 90% complete things I'm writing (it's been 90% complete for
> months)

Aren't they always? :)

> you'd write
> 
>   #
>   # A class all about books
>   #
>   # Author:  Jason Voegele
>   # Version: 1.0
>   #
> 
>   class ...

This seems very simple and clean, but I'd prefer some way of 
differentiating between normal comments and documentation comments (such 
as "documentation comments begin with ##").  Sometimes I find myself 
writing comments to maintenance programmers that really do not belong in 
the official published documentation of a class/module.

Jason