ruby-****@sourc*****
ruby-****@sourc*****
2004年 1月 23日 (金) 04:12:35 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
- == Specs
+ == How does it work?
- TODO
+ 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.
+
+ == Author
+
+ ((<lrz>))