problem with rdoc and extensions

Discussion in 'Ruby' started by Charles Mills, Oct 4, 2004.

  1. Hi,
    I am trying to use rdoc to document a C extension. The file structure
    of the extension is as follows:
    ext.h
    ext.c
    ext_class1.c
    ext_class2.c
    ext_class3.c
    ...

    where "EXT" is the module and "Class1", "Class2", etc are the classes
    defined under "EXT".
    So the name space looks like:
    EXT
    EXT::Class1
    EXT::Class2
    EXT::Class3
    ...


    'ext.h' contains a global variable:
    VALUE mEXT;
    which is references the Ruby module EXT at runtime.

    In 'ext_class1.c' (and friends) we have:

    #include "ext.h"

    /* ... */

    void Init_EXT_Class1(void)
    {
    rb_define_class_under(mEXT, "Class1", rb_cObject);
    /* define class methods ... */
    }

    In ext.c we have

    #include "ext.h"

    void Init_ext(void)
    {
    mEXT = rb_define_module("EXT");
    Init_EXT_Class1();
    Init_EXT_Class2();
    Init_EXT_Class3();
    /* ... */
    }

    So the problem is when documenting 'ext_class1.c' and friends rdoc
    can't figure out what the variable 'mEXT' is (the module the classes
    are defined under) and fails to document Class1 and friends.

    Any solutions?
    Putting everything in one .c file is not an option. :)

    -Charlie
    Charles Mills, Oct 4, 2004
    #1
    1. Advertising

  2. Here I am replying to my own post...
    I looked at the rdoc C parser, it doesn't look like rdoc maintains its
    state between each .c file. Is this what is going on?

    Made a few corrections to my last post:

    Hi,
    I am trying to use rdoc to document a C extension. The file structure
    of the extension is as follows:
    ext.h
    ext.c
    ext_class1.c
    ext_class2.c
    ext_class3.c
    ...

    where "EXT" is the module and "Class1", "Class2", etc are the classes
    defined under "EXT".
    So the name space looks like:
    EXT
    EXT::Class1
    EXT::Class2
    EXT::Class3
    ...


    'ext.h' contains a global variable:

    extern VALUE mEXT;

    which references the Ruby module EXT at runtime.

    In 'ext_class1.c' (and friends) we have:

    #include "ext.h"

    /* ... */

    void Init_EXT_Class1(void)
    {
    rb_define_class_under(mEXT, "Class1", rb_cObject);
    /* define class methods ... */
    }

    In ext.c we have

    #include "ext.h"

    VALUE mEXT;

    void Init_ext(void)
    {
    mEXT = rb_define_module("EXT");
    Init_EXT_Class1();
    Init_EXT_Class2();
    Init_EXT_Class3();
    /* ... */
    }

    So the problem is when documenting 'ext_class1.c' and friends rdoc
    can't figure out what the variable 'mEXT' is (the module the classes
    are defined under) and fails to document Class1 and friends.

    Any solutions?
    Putting everything in one .c file is not an option. :)

    -Charlie
    Charles Mills, Oct 5, 2004
    #2
    1. Advertising

  3. Charles Mills

    Dave Thomas Guest

    On Oct 4, 2004, at 18:36, Charles Mills wrote:

    > Here I am replying to my own post...
    > I looked at the rdoc C parser, it doesn't look like rdoc maintains its
    > state between each .c file. Is this what is going on?


    That's correct - it would be inappropriate to do that when RDoc is used
    (for example) to document all the Ruby extensions.

    I'm not sure of an easy way to handle your particular problem, apart,
    perhaps from an ugly cheat. In each .c file that defines classes based
    on the external module, put a definition of the module variable and the
    define_module line in an ifdef's out chunk of code (see, I said it was
    ugly)


    Cheers

    Dave
    Dave Thomas, Oct 5, 2004
    #3
  4. Charles Mills

    Guest

    On Tue, 5 Oct 2004, Dave Thomas wrote:

    >
    > On Oct 4, 2004, at 18:36, Charles Mills wrote:
    >
    >> Here I am replying to my own post...
    >> I looked at the rdoc C parser, it doesn't look like rdoc maintains its
    >> state between each .c file. Is this what is going on?

    >
    > That's correct - it would be inappropriate to do that when RDoc is used
    > (for example) to document all the Ruby extensions.
    >
    > I'm not sure of an easy way to handle your particular problem, apart,
    > perhaps from an ugly cheat. In each .c file that defines classes based
    > on the external module, put a definition of the module variable and the
    > define_module line in an ifdef's out chunk of code (see, I said it was
    > ugly)


    how about using cpp, or cat even, to inline all your c sources and the
    rdoc'ing one giant source file?

    -a
    --
    ===============================================================================
    | EMAIL :: Ara [dot] T [dot] Howard [at] noaa [dot] gov
    | PHONE :: 303.497.6469
    | A flower falls, even though we love it;
    | and a weed grows, even though we do not love it.
    | --Dogen
    ===============================================================================
    , Oct 5, 2004
    #4
  5. On Oct 4, 2004, at 9:34 PM, wrote:

    > On Tue, 5 Oct 2004, Dave Thomas wrote:
    >
    >>
    >> On Oct 4, 2004, at 18:36, Charles Mills wrote:
    >>
    >>> Here I am replying to my own post...
    >>> I looked at the rdoc C parser, it doesn't look like rdoc maintains
    >>> its
    >>> state between each .c file. Is this what is going on?

    >>
    >> That's correct - it would be inappropriate to do that when RDoc is
    >> used
    >> (for example) to document all the Ruby extensions.
    >>
    >> I'm not sure of an easy way to handle your particular problem, apart,
    >> perhaps from an ugly cheat. In each .c file that defines classes based
    >> on the external module, put a definition of the module variable and
    >> the
    >> define_module line in an ifdef's out chunk of code (see, I said it was
    >> ugly)

    >
    > how about using cpp, or cat even, to inline all your c sources and the
    > rdoc'ing one giant source file?


    That is a great idea. Tried it and it works well. You obviously don't
    get a list of all the .c files in the project, but that is not really a
    problem (if it become one Daves idea looks like it solves that).

    Thanks for the help,
    Charlie
    Charles Mills, Oct 5, 2004
    #5
  6. Charles Mills

    Dave Thomas Guest

    On Dec 30, 2004, at 7:06 PM, rinconj wrote:

    > I just encountered the same problem with libpcap-ruby.
    > I guess it's not much of a problem to cat all the files into one, but
    > it
    > certainly is something rdoc should improve with future releases.


    I missed the original -- what's the issue?
    Dave Thomas, Dec 31, 2004
    #6
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Andreas Schwarz
    Replies:
    6
    Views:
    242
    Randy W. Sims
    Jan 1, 2004
  2. Brian Schröder
    Replies:
    5
    Views:
    128
    Dave Thomas
    Sep 18, 2004
  3. Daniel Berger
    Replies:
    1
    Views:
    138
    Dave Thomas
    Nov 2, 2004
  4. Iwan van der Kleyn

    rdoc: how to add readme.rdoc as index.html?

    Iwan van der Kleyn, Apr 26, 2005, in forum: Ruby
    Replies:
    1
    Views:
    219
    Stefan Lang
    Apr 26, 2005
  5. Paul Van Delst

    How to use rdoc parsers outside of rdoc?

    Paul Van Delst, Jul 27, 2006, in forum: Ruby
    Replies:
    0
    Views:
    95
    Paul Van Delst
    Jul 27, 2006
Loading...

Share This Page