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.new(:ri) 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