RDoc enhancement proposal

[leon breedt]

Hi again

I have some proposals for updates to RDoc which may make life easier
for people wanting to document C extensions. These aren't just
requests, I'm quite willing to go ahead and implement them myself, I
just want to get a general feel of the approach to take.


1. Classes and modules defined across multiple files in C extensions
=====================================================

A current weakness (while not a problem for .rb files) when parsing C
extensions is that each file is regarded as an island for the purposes
of parsing. This is fine for small extensions, but for more complex
ones, this causes RDoc to not find classes or modules that were
defined in seperate files.

I propose providing a way to indicate that a set of files belong
together for the purposes of looking up module and class definitions.
This should not be needed for Ruby files, obviously.

I'm not too sure about the best approach to this yet, but I can state
I am rather opposed to the approach that concatenates *.c to a big .c
file and then runs RDoc on it.


2. Supporting documentation of generated C code
=======================================

This an issue where the items being generated affect the lookup of
classes/modules and methods by the RDoc parser.

I though a clean way to solve this problem would be to provide some
way for the developer to extend the abilities of the file parser by
providing hooks called at parser #scan() time.

Allowing the ability to add hooks to find the comment for a particular
class/method would be handy as well, since the C function implementing
a method could quite possibly be generated as well.

Implementing the above obviates the need to resort to
Document-class/Document-method, unless I have no place in the C code
to attach the comment.

This way, I can easily tell RDoc that DEFINE_SOME_CLASS(Basename) in
my C extension generates the following "AST" items:

class PrefixBasename, definition stored in cPrefixBasename (a VALUE)

method somemethod, defined in module SomeModule, implemented by C
function somefunc_Basename

---

The only disadvantages I can see for #2 is that people may implement
their hooks before seeing that things like
Document-class/Document-module exist, causing multiple varieties of
RDoc, all different.

But for corner cases where updating the RDoc parser proper doesn't
make sense (extensions are necessary for a specific project), hooks
could be invaluable.

Looking forward to any comments
Leon

 

[Tilman Sauerbeck]

--BXVAT5kNtrzKuDFl
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

1. Classes and modules defined across multiple files in C extensions
=====================================================

A current weakness (while not a problem for .rb files) when parsing C
extensions is that each file is regarded as an island for the purposes
of parsing. This is fine for small extensions, but for more complex
ones, this causes RDoc to not find classes or modules that were
defined in seperate files.

I propose providing a way to indicate that a set of files belong
together for the purposes of looking up module and class definitions.
This should not be needed for Ruby files, obviously.

See the attached patch for one way of how to fix this.
It's a bit hackish, though :]

--
Regards,
Tilman

--BXVAT5kNtrzKuDFl
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="rdoc-remember_classes.diff"

diff -aur ruby-1.8.2.orig/lib/rdoc/parsers/parse_c.rb ruby-1.8.2/lib/rdoc/parsers/parse_c.rb
--- ruby-1.8.2.orig/lib/rdoc/parsers/parse_c.rb 2004-09-09 04:48:32.000000000 +0200
+++ ruby-1.8.2/lib/rdoc/parsers/parse_c.rb 2005-01-23 12:11:51.244356576 +0100
@@ -170,6 +170,7 @@
parse_files_matching(/\.(c|cc|cpp|CC)$/)

@@known_bodies = {}
+ @@classes = {}

# prepare to parse a C file
def initialize(top_level, file_name, body, options, stats)
@@ -178,7 +179,6 @@
@options = options
@stats = stats
@top_level = top_level
- @classes = Hash.new
@file_dir = File.dirname(file_name)
end

@@ -208,7 +208,7 @@
parent_name = @known_classes[parent] || parent

if in_module
- enclosure = @classes[in_module]
+ enclosure = @@classes[in_module]
unless enclosure
$stderr.puts("Enclosing class/module '#{in_module}' for " +
"#{class_mod} #{class_name} not known")
@@ -228,7 +228,7 @@
cm.record_location(enclosure.toplevel)

find_class_comment(cm.full_name, cm)
- @classes[var_name] = cm
+ @@classes[var_name] = cm
@known_classes[var_name] = cm.full_name
end

@@ -483,7 +483,7 @@
# rb_include_module(rb_cArray, rb_mEnumerable);
def do_includes
@body.scan(/rb_include_module\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
- if cls = @classes[c]
+ if cls = @@classes[c]
m = KNOWN_CLASSES[m] || m
cls.add_include(Include.new(m, ""))
end
@@ -502,14 +502,14 @@
end

def find_class(raw_name, name)
- unless @classes[raw_name]
+ unless @@classes[raw_name]
if raw_name =~ /^rb_m/
- @classes[raw_name] = @top_level.add_module(NormalModule, name)
+ @@classes[raw_name] = @top_level.add_module(NormalModule, name)
else
- @classes[raw_name] = @top_level.add_class(NormalClass, name, nil)
+ @@classes[raw_name] = @top_level.add_class(NormalClass, name, nil)
end
end
- @classes[raw_name]
+ @@classes[raw_name]
end

# Remove #ifdefs that would otherwise confuse us

--BXVAT5kNtrzKuDFl--

 

[leon breedt]

See the attached patch for one way of how to fix this.
It's a bit hackish, though :]

I had a similar hack going, but I wasn't sure how likely Dave was to
accept it...
Then again, only C files have this problem, so perhaps its not *that* evil

Leon

 

[leon breedt]

See the attached patch for one way of how to fix this.
It's a bit hackish, though :]

Help, I really need a "Send in 5 minutes" button :>

A problem with your patch (as far as I can see), is that it would
introduce the artificial restriction that you get the .c file ordering
right on the rdoc command-line, because entries in @@classes would not
exist until the correct .c file has been parsed, and that would still
cause failures as now.

Requiring file ordering would violate principle of least surprise for me

Leon

 

[Tilman Sauerbeck]

See the attached patch for one way of how to fix this.
It's a bit hackish, though :]

Help, I really need a "Send in 5 minutes" button :>

A problem with your patch (as far as I can see), is that it would
introduce the artificial restriction that you get the .c file ordering
right on the rdoc command-line, because entries in @@classes would not
exist until the correct .c file has been parsed, and that would still
cause failures as now.

Requiring file ordering would violate principle of least surprise for me

Yeah, you are right. So far it works nicely for me, since my extension
aren't *that* complex

A bullet-proof solution would be nicer, of course