diff options
| -rw-r--r-- | class.c | 71 | ||||
| -rw-r--r-- | doc/images/boottime-classes.png | bin | 0 -> 28677 bytes | |||
| -rw-r--r-- | object.c | 19 | ||||
| -rw-r--r-- | template/Doxyfile.tmpl | 6 |
4 files changed, 92 insertions, 4 deletions
@@ -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 ? "+" : ""); } + +/*! + * \} + */ diff --git a/doc/images/boottime-classes.png b/doc/images/boottime-classes.png Binary files differnew file mode 100644 index 0000000000..b5fab75c41 --- /dev/null +++ b/doc/images/boottime-classes.png @@ -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 diff --git a/template/Doxyfile.tmpl b/template/Doxyfile.tmpl index e93d893120..0fd9462c69 100644 --- a/template/Doxyfile.tmpl +++ b/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 |
