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
