From: Nick Booker <nmbooker@...>
Date: 2011-02-28T22:54:38+09:00
Subject: Documenting multi-file C extensions

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