Documentation clean-up

This commit was SVN r699.

src/lam/lfc/object.h

@@ -3,7 +3,9 @@
  */
 
 /**
- * @file:
+ * @file
+ *
+ * Simple C-language object-oriented system.
  *
  * Simple C-language object-oriented system with single inheritance
  * and ownership-based memory management using a retain/release model.
@@ -12,7 +14,7 @@
  * descriptor.  The first element of the struct must be the parent
  * class's struct.  The class descriptor must be given a well-known
  * name based upon the class struct name: If the struct is sally_t,
- * the class info descriptor should be xxx_t_class_info.
+ * the class info descriptor should be sally_t_class_info.
  *
  * (a) To define a class
  *
@@ -20,6 +22,7 @@
  * should always be the parent class, and be called "super",
  * for example
  * 
+ * @code
  *   typedef struct sally_t sally_t;
  *   struct sally_t
  *   {
@@ -29,6 +32,7 @@
  *   };
  *
  *   extern lam_class_info_t sally_t_class_info;
+ * @endcode
  *
  * All classes must have a parent.
  * 
@@ -36,12 +40,14 @@
  * for this class, and should be the name of the class with
  * "_class_info" appended:
  *
+ * @code
  *   lam_class_info_t sally_t_class_info = {
  *     "sally_t",
  *     CLASS_INFO(parent_t),  // pointer to parent_t_class_info
  *     sally_construct,
  *     sally_destruct
  *   };
+ * @endcode
  *
  * This variable should be publically advertised using the "extern"
  * statement in the interface file as shown above.
@@ -53,12 +59,16 @@
  * The first thing sally_construct should do is run its parent's
  * constructor using the OBJ_CONSTRUCT_SUPER macro:
  *
+ * @code
  *   OBJ_CONSTRUCT_SUPER(obj, type_of_parent);
+ * @endcode
  *
  * Similarly, the las thing sally_destruct should do is run its
  * parents' destructor.
  *
+ * @code
  *   OBJ_DESTRUCT_SUPER(obj, type_of_parent);
+ * @endcode
  *
  * Other class methods may be added to the struct.
  *
@@ -66,7 +76,9 @@
  *
  * To create a instance of a class (an object) use OBJ_NEW:
  *
+ * @code
  *   sally_t *sally = OBJ_NEW(sally_t);
+ * @endcode
  *
  * which allocates memory of sizeof(sally_t) and runs the class's
  * "init" method.
@@ -74,9 +86,11 @@
  * Use OBJ_RETAIN, OBJ_RELEASE to do reference-count-based
  * memory management:
  *
+ * @code
  *   OBJ_RETAIN(sally);
  *   OBJ_RELEASE(sally);
  *   OBJ_RELEASE(sally);
+ * @endcode
  *
  * When the reference count reaches zero, the class's "fini" method
  * is run and the memory is freed.
@@ -90,15 +104,19 @@
  * necessary to initialize the memory, which is done using
  * OBJ_CONSTRUCT:
  *
+ * @code
  *   sally_t sally;
  *
  *   OBJ_CONSTRUCT(&sally, sally_t);
+ * @endcode
  *
  * The retain/release model is not necessary here, but before the
  * object goes out of scope, OBJ_DESTRUCT should be run to release
  * initialized resources:
  *
+ * @code
  *   OBJ_DESTRUCT(&sally);
+ * @endcode
  */
 
 #ifndef LAM_OBJECT_H
@@ -119,6 +137,10 @@ typedef struct lam_class_info_t lam_class_info_t;
 typedef void (*lam_construct_t) (lam_object_t *);
 typedef void (*lam_destruct_t) (lam_object_t *);
 
+
+/**
+ * Class descriptor.  This structure should be instantiated once for each class.  
+ */
 struct lam_class_info_t {
     const char *cls_name;
     lam_class_info_t *cls_parent;