ruby-****@sourc*****
ruby-****@sourc*****
2005年 9月 14日 (水) 10:28:34 JST
-------------------------
REMOTE_ADDR = 218.231.161.82
REMOTE_HOST =
REMOTE_USER = ruby-gnome2-hiki
URL = /hiki.cgi?using_extdoc
-------------------------
TITLE = Using Extdoc.rb
KEYWORD =
= Using Extdoc.rb
This document introduces Extdoc, the documentation system used to generate API reference from source files (parsing C comments).
Extdoc is able to produce Text/ASCII, Docbook/XHTML and RD+ documents.
It is currently used in several Ruby libraries, such as Ruby/GStreamer, Ruby/Libgda, Ruby/Libburn, etc...
== Getting started
=== Sources
Sources can be downloaded from anonymous CVS, using the following instructions:
$ cvs -d:pserver:anony****@cvs*****:/cvsroot/ruby-gnome2 login
$ cvs -z3 -d:pserver:anony****@cvs*****:/cvsroot/ruby-gnome2 co tools/extdoc
(when prompted for a password for anonymous, simply press the Enter key).
You can also browse the sources via the ((<web interface|URL:http://cvs.sourceforge.net/viewcvs.py/ruby-gnome2/tools/extdoc/>)).
=== Install
Once you have downloaded the sources, use the following commands in order to setup and install Extdoc:
$ ruby install.rb config
$ ruby install.rb setup
$ su
$ ruby install.rb install
Check that Extdoc is correctly installed:
$ extdoc -V
0.2.0
== How does it work?
Extdoc parses C comments ((({/* ... */}))) from C source files (*.c). You don't need to adopt a particular coding style for your comments, Extdoc should parse all styles. Note that Extdoc won't parse C++ comments ((({// ...}))).
Each class/module of your library should be separated into one distinct file. For example, the class Bar::Coffee can be written in rbbarcoffee.c.
Each comment should start by what we will call a ((*tag*)). They are tags for classes, modules, class methods, methods, and constants.
Tags are followed by a short description, and then by a long description:
/* TagName: Short Description
* Long description.
*/
=== Classes
:Tag
(({Class})).
:Short Description
This is the class' name (including nested modules).
:Long Description
Describe the class.
Example:
/* Class: Bar::Coffee
* This class makes excellent coffee.
*/
=== Modules
Same as classes, just use the (({Module})) tag instead.
=== Class methods
:Tag
(({Class method})).
:Short Description
This is the method's signature.
:Long Description
Describe the method, starting with parameters, then a long description, and finally the return value.
Example:
/*
* Class method: new(expresso=true)
* expresso: true for an Italian coffee, false otherwise.
*
* Creates a new coffee.
*
* Returns: a newly created Bar::Coffee object.
*/
=== Methods
Same as class methods, just use the (({Method})) tag instead.
Example:
/* Method: sugar!
* Adds some sugar.
* Returns: self.
*/
=== Constants
:Tag
(({Constant})).
:Short Description
This is the constant's name.
:Long Description
Describe the constant.
Example:
/* Constant: RISTRETTO
* A ristretto shot.
*/
=== Aliases
Automatically parsed, by looking for (({rb_define_alias})) calls.
=== Setters
Automatically parsed, by looking for (({G_DEF_SETTER})) and (({G_DEF_SETTERS})) calls.
=== GLib Enums, Flags and Signals
Automatically parsed, by inspecting each class.
== Full Example
#include "rbbar.c"
/* Class: Bar::Coffee
* This class makes excellent coffee.
*/
VALUE cBarCoffee;
/*
* Class method: new(expresso=true)
* expresso: true for an Italian coffee, false otherwise.
*
* Creates a new coffee.
*
* Returns: a newly created Bar::Coffee object.
*/
static VALUE
rb_bar_coffee_new (int argc, VALUE *argc, VALUE self)
{
/* ... */
}
/* Method: sugar!
* Adds some sugar.
* Returns: self.
*/
static VALUE
rb_bar_coffee_sugar (VALUE self)
{
/* ... */
}
void rb_bar_init (VALUE mBar)
{
cBarCoffee = G_DEF_CLASS (BAR_TYPE_COFFEE, "Coffee", mBar);
rb_define_method (cBarCoffee, "initialize", rb_bar_coffee_new, -1);
rb_define_method (cBarCoffee, "sugar!", rb_bar_coffee_sugar, 0);
/* Constant: RISTRETTO
* A ristretto shot.
*/
rb_define_constant (cBarCoffee, "RISTRETTO",
INT2FIX (BAR_COFFEE_RISTRETTO));
}
=== Usage
TODO
== Bugs
(1) GLib Enums, Flags and Signals are not yet described. They are just present in the documentation, but with an empty description.
(2) Sometimes, methods' parameters are not sorted in the right order in the documentation.
== Author
((<lrz>))