Documenting multi-file C extensions

[Nick Booker]

Hi.

I'm having some trouble getting rdoc to recognise my module structure
in a
C extension.
It generates documentation for the top-level module RBSpool, which is
declared in rbspool.c, but my classes (which are defined in separate C
files, named, for example, RBSpool_Server.c)
are found but not listed in the generated HTML.

Can anybody suggest what I'm doing wrong (or point me in the direction
of someone / something who can?)

The output of "rake doc" is here:
sfnick@oak:ext$ rake rdoc
(in /home/sfnick.main/Documents/customers/xisl/text-api-ruby/xitext-
ruby/ruby-xtapi)
rm -r doc/site/api

rbspool.c: m
RBSpool_Server.c: c
Enclosing class/module 'mRBSpool' for class Server not known
....
Generating HTML...

Files: 2
Classes: 0
Modules: 1
Methods: 4
Elapsed: 0.037s

The output HTML, when rendered, looks (roughly) like this:
Files Classes Methods
ext/RBSpool_Server.c RBSpool
ext/rbspool.c
--------------------
Module RBSpool
In: ext/rbspool.c
Document-class: RBSpool
The RBSpool module encapsulates [snip]...

An abridged version of the relevant code files (.c, .h, Rakefile) are
listed below.

This is the main module, with irrelevant lines snipped:

/**
[snip]
*/

#include <ruby.h>
#include "extconf.h"

#include "RBSpool_Error.h"
#include "RBSpool_Server.h"
#include "RBSpool_Job.h"
#include "RBSpool.h"

// [snip]

VALUE mRBSpool = Qnil;

/*
* Document-class: RBSpool
*
* The RBSpool module encapsulates access to the Xi-Text and GNUSpool
* APIs via Ruby.
*/

void Init_rbspool(void) {
/* Don't initialise twice! */
if (mRBSpool != Qnil) return;

/* Create a module "RBSpool". */
mRBSpool = rb_define_module("RBSpool");

/* See RBSpool_Server.c and RBSpool_Server.h */
Init_rbspool_server();

// [snip]
}

These are the contents of RBSpool_Server.c, with irrelevant lines
snipped:

/**
* [snip]
*/
#include <ruby.h>
#include "extconf.h"

#include "RBSpool.h"
#include "RBSpool_Server.h"
// [snip]
VALUE cRBSpool_Server = Qnil; /* class RBSpool::Server */
// [snip]

/*
* Document-class: RBSpool::Server
*
* The RBSpool::Server class encapsulates a connection to a Xi-Text
server's
* API library.
*/
void Init_rbspool_server(void)
{
/* Make sure we don't build it more than once */
if (cRBSpool_Server != Qnil) return;

cRBSpool_Server = rb_define_class_under(mRBSpool, "Server",
rb_cObject);
// [snip]
}

These are the contents of RBSpool.h, with irrelevant lines snipped:
/**
[snip]
*/

#include <ruby.h>

// [snip]

extern VALUE mRBSpool;

// [snip]


And here's the rdoc bit of my Rakefile:
require 'rake/rdoctask'

RDOC_FILES = FileList["ext/rbspool.c", "ext/RBSpool_Server.c"]

Rake::RDocTask.new do |rd|
rd.main = "ext/rbspool.c"
rd.rdoc_dir = "doc/site/api"
rd.rdoc_files.include(RDOC_FILES)
end

Rake::RDocTask.newri) do |rd|
rd.main = "ext/rbspool.c"
rd.rdoc_dir = "doc/ri"
rd.options << "--ri-system"
rd.rdoc_files.include(RDOC_FILES)
end


Cheers,

Nick Booker