Doxy-comments.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@23902 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

class.c

@@ -9,6 +9,20 @@
 
 **********************************************************************/
 
+/*!
+ * \defgroup class Classes and their hierarchy.
+ * \par Terminology
+ * - class: same as in Ruby.
+ * - singleton class: class for a particular object
+ * - eigenclass: = singleton class
+ * - metaclass: class of a class. metaclass is a kind of singleton class.
+ * - metametaclass: class of a metaclass.
+ * - meta^(n)-class: class of a meta^(n-1)-class.
+ * - attached object: A singleton class knows its unique instance.
+ *   The instance is called the attached object for the singleton class.
+ * \{
+ */
+
 #include "ruby/ruby.h"
 #include "ruby/st.h"
 #include "node.h"
@@ -16,6 +30,18 @@
 
 extern st_table *rb_class_tbl;
 
+/**
+ * Allocates a struct RClass for a new class.
+ *
+ * \param flags     initial value for basic.flags of the returned class.
+ * \param klass     the class of the returned class.
+ * \return          an uninitialized Class object.
+ * \pre  \p klass must refer \c Class class or an ancestor of Class.
+ * \pre  \code (flags | T_CLASS) != 0  \endcode
+ * \post the returned class can safely be \c #initialize 'd.
+ *
+ * \note this function is not Class#allocate.
+ */
 static VALUE
 class_alloc(VALUE flags, VALUE klass)
 {
@@ -30,6 +56,16 @@ class_alloc(VALUE flags, VALUE klass)
     return (VALUE)obj;
 }
 
+
+/*!
+ * A utility function that wraps class_alloc.
+ *
+ * allocates a class and initializes safely.
+ * \param super     a class from which the new class derives.
+ * \return          a class object.
+ * \pre  \a super must be a class.
+ * \post the metaclass of the new class is Class.
+ */
 VALUE
 rb_class_boot(VALUE super)
 {
@@ -42,6 +78,13 @@ rb_class_boot(VALUE super)
     return (VALUE)klass;
 }
 
+
+/*!
+ * Ensures a class can be derived from super.
+ *
+ * \param super a reference to an object.
+ * \exception TypeError if \a super is not a Class or \a super is a singleton class.
+ */
 void
 rb_check_inheritable(VALUE super)
 {
@@ -54,6 +97,13 @@ rb_check_inheritable(VALUE super)
     }
 }
 
+
+/*!
+ * Creates a new class.
+ * \param super     a class from which the new class derives.
+ * \exception TypeError \a super is not inheritable.
+ * \exception TypeError \a super is the Class class.
+ */
 VALUE
 rb_class_new(VALUE super)
 {
@@ -189,6 +239,13 @@ rb_singleton_class_attached(VALUE klass, VALUE obj)
 }
 
 
+/*!
+ * Creates a meta^(n+1)-class for a meta^(n)-class.
+ * \param metaclass     a class of a class
+ * \return              the created meta^(n+1)-class.
+ * \pre \a metaclass is a metaclass
+ * \post the class of \a metaclass is the returned class.
+ */
 static VALUE
 make_metametaclass(VALUE metaclass)
 {
@@ -224,6 +281,16 @@ make_metametaclass(VALUE metaclass)
 }
 
 
+/*!
+ * \internal
+ * Creates a singleton class for an object.
+ *
+ * \note DO NOT USE the function in an extension libraries. Use rb_singleton_class.
+ * \param obj    An object.
+ * \param super  A class from which the singleton class derives.
+ *        \note \a super is ignored if \a obj is a metaclass.
+ * \return       The singleton class of the object.
+ */
 VALUE
 rb_make_metaclass(VALUE obj, VALUE super)
 {
@@ -1040,3 +1107,7 @@ rb_scan_args(int argc, const VALUE *argv, const char *fmt, ...)
 	rb_raise(rb_eArgError, "wrong number of arguments (%d for %d%s)",
 		 argc, n_mand, f_var ? "+" : "");
 }
+
+/*!
+ * \}
+ */

object.c

@@ -2449,7 +2449,24 @@ boot_defmetametaclass(VALUE klass, VALUE metametaclass)
  */
 
 
-/*
+/*!
+ *--
+ * Initializes the world of objects and classes.
+ *
+ * At first, the function bootstraps the class hierarchy.
+ * It initializes the most fundamental classes and their metaclasses.
+ * - \c BasicObject
+ * - \c Object
+ * - \c Module
+ * - \c Class
+ * After the bootstrap step, the class hierarchy becomes as the following
+ * diagram.
+ *
+ * \image html boottime-classes.png
+ *
+ * Then, the function defines classes, modules and methods as usual.
+ * \ingroup class
+ *++
  *  <code>BasicObject</code> is the parent class of all classes in Ruby.
  *  It's an explicit blank class.  <code>Object</code>, the root of Ruby's
  *  class hierarchy is a direct subclass of <code>BasicObject</code>.  Its

template/Doxyfile.tmpl

@@ -69,7 +69,7 @@ HIDE_UNDOC_MEMBERS     = NO
 HIDE_UNDOC_CLASSES     = NO
 HIDE_FRIEND_COMPOUNDS  = NO
 HIDE_IN_BODY_DOCS      = YES
-INTERNAL_DOCS          = NO
+INTERNAL_DOCS          = YES
 CASE_SENSE_NAMES       = NO
 HIDE_SCOPE_NAMES       = NO
 SHOW_INCLUDE_FILES     = YES
@@ -112,7 +112,7 @@ EXCLUDE_SYMBOLS        =
 EXAMPLE_PATH           = 
 EXAMPLE_PATTERNS       = 
 EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = 
+IMAGE_PATH             = <%= "#{srcdir}/doc/images" %>
 FILTER_PATTERNS        = 
 FILTER_SOURCE_FILES    = YES
 #---------------------------------------------------------------------------
@@ -253,7 +253,7 @@ CALLER_GRAPH           = NO
 GRAPHICAL_HIERARCHY    = NO
 DIRECTORY_GRAPH        = NO
 DOT_IMAGE_FORMAT       = png
-DOT_PATH               = <%= dot %>
+DOT_PATH               =
 DOTFILE_DIRS           = 
 DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 0