ruby-changes:12217
From: yugui <ko1@a...>
Date: Tue, 30 Jun 2009 01:39:40 +0900 (JST)
Subject: [ruby-changes:12217] Ruby:r23902 (trunk): Doxy-comments.
yugui 2009-06-30 01:39:28 +0900 (Tue, 30 Jun 2009) New Revision: 23902 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=23902 Log: Doxy-comments. Added directories: trunk/doc/images/ Added files: trunk/doc/images/boottime-classes.png Modified files: trunk/class.c trunk/object.c trunk/template/Doxyfile.tmpl Index: doc/images/boottime-classes.png =================================================================== Cannot display: file marked as a binary type. svn:mime-type = image/png Property changes on: doc/images/boottime-classes.png ___________________________________________________________________ Name: svn:mime-type + image/png Index: object.c =================================================================== --- object.c (revision 23901) +++ object.c (revision 23902) @@ -2449,7 +2449,24 @@ */ -/* +/*! + *-- + * 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 Index: class.c =================================================================== --- class.c (revision 23901) +++ class.c (revision 23902) @@ -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 @@ 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 @@ 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 @@ } } + +/*! + * 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 @@ } +/*! + * 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 @@ } +/*! + * \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_raise(rb_eArgError, "wrong number of arguments (%d for %d%s)", argc, n_mand, f_var ? "+" : ""); } + +/*! + * \} + */ Index: template/Doxyfile.tmpl =================================================================== --- template/Doxyfile.tmpl (revision 23901) +++ template/Doxyfile.tmpl (revision 23902) @@ -69,7 +69,7 @@ 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 @@ EXAMPLE_PATH = EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO -IMAGE_PATH = +IMAGE_PATH = <%= "#{srcdir}/doc/images" %> FILTER_PATTERNS = FILTER_SOURCE_FILES = YES #--------------------------------------------------------------------------- @@ -253,7 +253,7 @@ 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 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/