Allow Aggregating Data From Multiple Sources

[adamsanderson]

I tried looking through RDoc's docs and source, but didn't really see a good way to do this. My goal was to generate docs and then pull in extra data from another source to provide extra content.

For instance the RubySpec specs are very well formatted, it would be awesome to scan then and say annotate the RDoc for Date#+ with the it or should clauses in date's add_spec.rb. The final documentation for Date#+ would then read:

Return a new Date object that is +n+ days later than the
current one.

+n+ may be a negative value, in which case the new Date
is earlier than the current one; however, #-() might be
more intuitive.

If +n+ is not a Numeric, a TypeError will be thrown.  In
particular, two Dates cannot be added to each other.

Spec:
* should add a number of days to a Date
* should add a negative number of days to a Date
* should raise an error on non numeric parameters

Anyways, I thought I would open this issue for comments. If someone wanted to point me in the right direction, I'd like to at least try it.

[drbrain]

I think the best way to accomplish this would be through a parser for spec files. https://github.com/rdoc/rdoc-rake is a parser for rake files that you could use as an example.

Instead of creating new classes to contain spec data the parser would look up the corresponding class and add the "Spec:" section to the existing comment.

This may require some changes to rdoc to ensure that the spec parser runs after other directories are parsed, but I would be happy to assist with those.

[adamsanderson]

Hey thanks, it was the bit around ensuring rdoc runs the spec parsing after the other directories were parsed where I thought I'd need help since I think rdoc tends to replace comments instead of append to them (?).

[drbrain]

The ruby parser overwrites method comments but not class comments. Usually classes and modules are extended through reopening but defining a method twice for the same class is not a good idea. Try running rdoc on this example:

# class comment 1
class C
  # method comment 1
  def m
  end
end

# class comment 2
class C
  # method comment 2
  def m
  end
end

If you write a custom parser for spec files this does not have to be true. You can look up a method and append to its comment instead of overwriting it just like for a class.

[adamsanderson]

Great, then it's just a matter of ensuring the correct ordering (ie: stdlib and then the specs).

[drbrain]

And writing a parser for specs, of course

[drbrain]

Closing this bug as I am not going to write the spec parser.

[adamsanderson]

No problem, thanks for the information :)