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:
[email protected]: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

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs