> ##
> # 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

I like this a lot.  Plus % is used in sprintf strings so it is not like
it is some off-the-wall character for something like this.  I agree that
using @ is not good since it is used in Ruby names.

> >
> > What about something completely different,
> > like the really simple formatting in a Wiki?
> 
> I don't know enough about Wikis to say :-\

I kind of thought that is what RD was like.  It seems like it is similar
in some senses to the Wiki syntax that I have seen (though I'm no
expert.) In general though I think that something like this is good
since it is mostly orthogonal to any particular output format.  Having
XML or HTML tags in the comments lends an HTML-centric flavor to the
documentation.  Of course these days almost anyone who programs knows at
least a little HTML, so maybe it isn't that bad.

I think in some ways this problem has two parts as far as the syntax is
concerned:

- The tags used for indicating special information (author, version,
  parameter descriptions, etc.)

- The syntax for formatting the output of the documentation (i.e.
  having italics, fixed fonts for code example sections, paragraphs,
  links, etc.)

For JavaDoc, they use the @ tags for the special information and HTML
style tags for formatting.  I like Jason's suggestion of using the %
symbol for the special information tags, but the question remains what
should be used for formatting.  What is most similar to Ruby in its ease
of creation and reading?  I think that is the question we need to
answer.  Ruby's documentation standard should be up to par with the
language itself.

Ryan Leavengood