>     >Personally, RDtool has never fit inside my head. I've played
>     >with it some, but it never seemed (to me) an especially
>     >Ruby-like solution.
>     >
>     >> I, for one, favor a tool that uses a consistent set
>     >> of tags and conventions across multiple languages
>     >> (like Java, C++, and Ruby for starters).
>     >
>     >Hmm, that's fine with me. Hadn't given it any thought.
> 
> Now given that, how does everyone feel about javadoc-style tags?
> The drawback is that @param and such look like instance
> variables.  But I find that easier to type than an XML-ish
> thing.

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
class Book

    ##
    # Returns the value of the @author field (which would be a
    # very bad comment in anything but this contrived example)
    #
    # %return The name of the author
    def author
        @author
    end
end

> 
> What about something completely different,
> like the really simple formatting in a Wiki?

I don't know enough about Wikis to say :-\

Jason Voegele