From: Austin Ziegler <halostatue@...>
Date: 2005-05-07T01:53:54+09:00
Subject: Re: rdoc, how is about :br: ?

On 5/4/05, Dr Balwinder S Dheeman <bsd.SANSPAM@cto.homelinux.net> wrote:
> Hi rdoc experts!
> 
> How is about adding a *:br:* directive? For example, I have a code like:

I don't believe that this would be a good idea. I'm presuming that you
are trying to indicate ways in which #list can be called? Try one of
the list formats instead. When he created rdoc initially, Dave Thomas
tried very hard to keep most formatting out of the documentation, and
I (for the most part) agree with him.

I think that I'd rather see support for keyed external documentation
(so that I can have documentation *separate* from the immediate method
for purposes of translation; this would also make it possible to have
"virtual" documentation for meta-methods) and classification changes.
The latter would allow me to do:

    # The writing pointer for ...
  attr_reader :y
  def y=(yy) #:classify attribute:
    ...
  end

instead of:

    # The writing pointer for ...
  attr_accessor :y
  def y=(yy) #:nodoc:
    ...
  end

Those two items would be far more useful than anything else for me at
this point.

-austin
-- 
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca