ruby-****@sourc*****
ruby-****@sourc*****
2004年 1月 23日 (金) 04:15:20 JST
-------------------------
REMOTE_ADDR = 217.117.55.140
REMOTE_HOST =
URL = http://ruby-gnome2.sourceforge.jp/?using_extdoc
-------------------------
= 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.
+ == 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>))