RDoc now does constants

ruby-talk
1

I’ve added experimental support for documenting constants to RDoc. Right
now it’s only in the CVS version, and only the default HTML template
makes use of the data when generating output.

I’d be interested in any feedback

Cheers

Dave

2

Does this mean that Structs will now be
documented? There was some discussion
of this on irc last night.

Hal

···

----- Original Message -----
From: “Dave Thomas” dave@pragprog.com
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Sent: Friday, August 01, 2003 12:19 PM
Subject: RDoc now does constants

I’ve added experimental support for documenting constants to RDoc. Right
now it’s only in the CVS version, and only the default HTML template
makes use of the data when generating output.

I’d be interested in any feedback

–
Hal Fulton
hal9000@hypermetrics.com

3

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.

So… I thought that by adding constants I gave us all a chance to
experiment with Structs as well. If it turns out that I need to add
additional support for them too, then I’ll do it.

Cheers

Dave

4

Well, call me crazy, but I sometimes create a Struct
and later (usually as an afterthought) add methods
to it.

Personally, I see nothing wrong with this. Some, though,
will perhaps say I should refactor and make my Structs
into “real” classes.

Hal

···

----- Original Message -----
From: “Dave Thomas” dave@pragprog.com
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Sent: Friday, August 01, 2003 3:35 PM
Subject: Re: RDoc now does constants

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.

So… I thought that by adding constants I gave us all a chance to
experiment with Structs as well. If it turns out that I need to add
additional support for them too, then I’ll do it.

–
Hal Fulton
hal9000@hypermetrics.com

5

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

···

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.

6

Hal E. Fulton wrote:

Well, call me crazy, but I sometimes create a Struct
and later (usually as an afterthought) add methods
to it.

Me too - but Structs and classes are different enough to make that
dangerous at times, so I try not to do it too often.

Personally, I see nothing wrong with this. Some, though,
will perhaps say I should refactor and make my Structs
into “real” classes.

Something that can bite you when you do this is:

S = Struct.new(:a)
class S
def getA
@a
end
end

s = S.new(123)
p s.getA #=> nil

Because of this inconsistency, I now subclass Structs a lot less than I
used to.

Now what I’m experimenting with is something like this:

class A
construct_with :a, :b

  def other_method
    @a += @b ...
  end

end

This is a simple code generator which works inside a real class, giving
me the best of both worlds. It generates a default #initialize method
that sets the instance variables (in this case @a and @b) and generates
accessor methods for each.

Cheers

Dave

7

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 :slight_smile:

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