William Webber wrote:

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

Umm.. it is a class :)

The Struct is not named, and is effectively anonymous at this point. The 
person who wrote this created a class with a predefined set of 
accessors. RDoc will document the class (but not know about the 
accessors by default).

Personally, I think this is not particularly good style. It would made 
the code clearer just to have the 11 attr_accessor statements inside the 
class.

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

OK, but take the case you showed previously. What should RDoc document 
for it? The struct has no name, and is immediately subclassed. How could 
I reasonably document it as a separate entity?


Cheers


Dave