From: William Webber <wew@...>
Date: 2003-08-02T20:31:30+09:00
Subject: Re: RDoc now does constants

On Sat, Aug 02, 2003 at 05:35:21AM +0900, Dave Thomas wrote:
> Hal E. Fulton wrote:
> 
> >Does this mean that Structs will now be
> >documented? There was some discussion 
> >of this on irc last night.
> 
> You could do something like:
> 
>    # A Person is used to hold information on
>    # interested parties.
>    # name:  the person's name
>    # dob:   the date of birth (Date)
> 
>    Person = Struct.new(:name, :dob)
> 
> However, for now I'm not automatically extracting Struct information: 
> there are too many heuristics involved. I'm also concerned that I don't 
> promote Structs as first-class classes, simply because when developer's 
> user Structs they are often not considered to be at the same level as 
> other classes.

Hi all!

I was the one discussing documenting structs on irc, and also who
submitted the enhancement request on rdoc.sourceforge.net.  The
class this question came up with was net/imap.rb, which makes use
of structs heavily to hold response/reply information.  Documenting
structs as constants works out ok.  However, some structs in net/imap.rb
have this form:

    class BodyTypeBasic < Struct.new(:media_type, :subtype,
                                     :param, :content_id,
                                     :description, :encoding, :size,
                                     :md5, :disposition, :language,
                                     :extension)
       # some (minor) methods
    end

and these end up documented as classes, not constants, even though
they are closely related to the other (simple) structs, which is not
optimal.

I guess the other issue is, what would the user of rdoc expect
(extending matz's principle of "least surprise" to documentation as
well).  If they saw a reference to, say, Net::IMAP::MailboxList in the
source code or in documentation comments, would they be surprised not
to find it listed under the list of classes for Net::IMAP?  I mean,
whether it is deserves to be treated as a "real class" or not, it is
after all a type, and since Ruby makes all types classes (including
what are "primitive" types in other languages), does it really make
sense for Ruby's documentation system to demur?  Would a nuby even
think to look under the list of class constants, or if they did would
they readily understand why they found it there?

William