more documentation

README.html

@@ -32,37 +32,76 @@
 <p>This can be installed via the usual configure, make, make install cycle. For gentoo users am ebuild is added under docs.</p>
 <h3 id="api-doc">API DOC</h3>
 <p>To generate the api doc a patched version of doxygen is neccessary. A patch is included under docs.</p>
-<p><em>make docs</em> creates the api doc.</p>
+<p><code>make docs</code> creates the api doc.</p>
 <h3 id="test-coverage-report">TEST COVERAGE REPORT</h3>
 <p>gcov and lcov are needed to build these.</p>
-<p>The source has to be configured with <em>configure --enable-gcov</em>. <em>make coverage-html</em> creates the converage reports then.</p>
+<p>The source has to be configured with <code>configure --enable-gcov</code>. <code>make coverage-html</code> creates the converage reports then.</p>
 <h2 id="usage">USAGE</h2>
 <h3 id="api">API</h3>
+<p>The public API consists of several preprocessor macros and some functions. When you look through the code you will find other symbols (functions or macros) which might seem useful. Here I try to focus on the neccessaties for using the library.</p>
 <h4 id="function-like-macros---class-creation">function-like macros - class creation</h4>
 <ul>
-<li><strong>TR_CLASS(name):</strong> Declare a new class.</li>
-<li><strong>TR_CREATE_CLASS(name, parent, ...):</strong> Create a new class.</li>
-<li><strong>TR_EXTENDS(parent):</strong> Extend another class</li>
+<li><code>TR_CLASS(name)</code>: Declare a new class.</li>
+<li><code>TR_CREATE_CLASS(name, parent, ...)</code>: Create a new class.</li>
+<li><code>TR_EXTENDS(parent)</code>: Extend another class</li>
 </ul>
 <h4 id="function-like-macros---class-information">function-like macros - class information</h4>
 <ul>
-<li><strong>TR_GET_CLASS(object):</strong> Get the class of the given object.</li>
-<li><strong>TR_HAS_PARENT(class):</strong> Check if the class extends another class.</li>
-<li><strong>TR_IS_OBJECT(obj):</strong> Check that the given pointer is really an instance of a class.</li>
-<li><strong>TR_INSTANCE_OF(class, obj):</strong> Check that the given obj is an instance of class.</li>
+<li><code>TR_GET_CLASS(object)</code>: Get the class of the given object.</li>
+<li><code>TR_HAS_PARENT(class)</code>: Check if the class extends another class.</li>
+<li><code>TR_IS_OBJECT(obj)</code>: Check that the given pointer is really an instance of a class.</li>
+<li><code>TR_INSTANCE_OF(class, obj)</code>: Check that the given obj is an instance of class.</li>
 </ul>
 <h4 id="function-like-macros---interface-selector-helper">function-like macros - interface selector helper</h4>
 <ul>
-<li><strong>TR_CALL(object, iface, method, ...):</strong> Call the interface implementation of the class or one of the parent classes of object.</li>
-<li><strong>TR_RETCALL(object, iface, method, ret, ...):</strong> Same as TR_CALL but with return value.</li>
-<li><strong>TR_PARENTCALL(object, iface, method, ...):</strong> Directly call the implementation within the parent class.</li>
+<li><code>TR_CALL(object, iface, method, ...)</code>: Call the interface implementation of the class or one of the parent classes of object.</li>
+<li><code>TR_RETCALL(object, iface, method, ret, ...)</code>: Same as TR_CALL but with return value.</li>
+<li><code>TR_PARENTCALL(object, iface, method, ...)</code>: Directly call the implementation within the parent class.</li>
 </ul>
 <h4 id="function-like-macros---interface-creation">function-like macros - interface creation</h4>
 <ul>
-<li><strong>TR_INTERFACE(name):</strong></li>
-<li><strong>TR_CREATE_INTERFACE(name, nfunc):</strong></li>
-<li><strong>TR_IF(name):</strong></li>
-<li><strong>TR_INIT_IFACE(name, ...):</strong></li>
+<li><code>TR_INTERFACE(name)</code>: Declare a new inerface.</li>
+<li><code>TR_CREATE_INTERFACE(name, nfunc)</code>: Create the new interface.</li>
+<li><code>TR_INIT_IFACE(name, ...)</code>: Create an interface implementation and assign functions to it.</li>
+<li><code>TR_IF(name)</code>: Convenience for getting an interface implementation by name. Used when assigning an interface to a class.</li>
+</ul>
+<h4 id="function-like-macros-for-the-class-interface">function-like macros for the class interface</h4>
+<p>The valious constructor and destructors are also assigned to an interface. The is the only interface every class MUST have so that instances can be created and destroyed. At least a constructor and a destructor must be assigned to this interface. The following selectors then utilize the interface to create and destroy instances.</p>
+<ul>
+<li><code>TR_new(class, ...)</code>: Create a new instance of a class with a variable argument list for the constructor interface.</li>
+<li><code>TR_newv(class, args)</code>: Same as <em>TR_new</em> but accepts a va_list* for the constructor arguments.</li>
+<li><code>TR_delete(object)</code>: Destroy an instance.</li>
+<li><code>TR_clone(object)</code>: Call an constructor that accepts another instance to create a clone from this instance.</li>
+</ul>
+<h4 id="selector-functions-subjectobserver-interface">selector functions subject/observer interface</h4>
+<p>These are in fact two interfaces that can be used to implement the subject/observer design pattern.</p>
+<ul>
+<li><code>TR_subjectAttach(Subject, Observer)</code>: Add an observer to a subject. The concrete implementation has to take care of memory management etc.</li>
+<li><code>TR_subjectDetach(Subject, Observer)</code>: Remove an observer from a subject.</li>
+<li>`TR_notify(Subject):* Notify all registered observer of an event.</li>
+<li><code>TR_observerUpdate(Observer, Subject)</code>: This must be called in TR_subjectNotify to inform a registered observer of an event.</li>
+</ul>
+<h4 id="selector-functions-indexable-interface">selector functions indexable interface</h4>
+<ul>
+<li><code>TR_getIndex(Indexable)</code>: Get a unique index of an instance. How this is created is subject of the concrete implementation.</li>
+</ul>
+<h4 id="selector-functions">selector functions</h4>
+<ul>
+<li><code>TR_serializedSize(Serializable)</code>: Get the size of the serialized instance.</li>
+<li><code>TR_serialize(Serializable, unsigned char * serialized)</code>: Serialize the instance into the serialized buffer. The buffer has to be large enough to hold the serialized instance.</li>
+<li><code>TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)</code>: Initialize the instance with the serialized data stored in serialized.</li>
+</ul>
+<h4 id="memory-management---functions">memory management - functions</h4>
+<ul>
+<li><code>void * TR_malloc(size_t)</code>:</li>
+<li><code>void * TR_calloc(size_t, size_t)</code>:</li>
+<li><code>void * TR_reference(void *)</code>:</li>
+<li><code>size_t TR_getSize(void *)</code>:</li>
+<li><code>void TR_cleanup()</code>:</li>
+</ul>
+<h4 id="memory-management---macros">memory management - macros</h4>
+<ul>
+<li><code>TR_MEM_FREE(seg)</code>:</li>
 </ul>
 <h3 id="example">EXAMPLE</h3>
 <h4 id="optimized-memory-management">optimized memory management</h4>

README.md

@@ -76,14 +76,14 @@ cycle. For gentoo users am ebuild is added under docs.
 To generate the api doc a patched version of doxygen is
 neccessary. A patch is included under docs.
 
-*make docs* creates the api doc.
+`make docs` creates the api doc.
 
 ### TEST COVERAGE REPORT
 
 gcov and lcov are needed to build these.
 
-The source has to be configured with *configure --enable-gcov*.
-*make coverage-html* creates the converage reports then.
+The source has to be configured with `configure --enable-gcov`.
+`make coverage-html` creates the converage reports then.
 
 
 USAGE
@@ -91,36 +91,96 @@ USAGE
 
 ### API ###
 
+The public API consists of several preprocessor macros and some functions.
+When you look through the code you will find other symbols (functions or
+macros) which might seem useful. Here I try to focus on the neccessaties
+for using the library.
+
 #### function-like macros - class creation ####
 
-* **TR\_CLASS(name):** Declare a new class. 
-* **TR\_CREATE\_CLASS(name, parent, ...):** Create a new class.
-* **TR\_EXTENDS(parent):** Extend another class
+* `TR_CLASS(name)`: Declare a new class. 
+* `TR_CREATE_CLASS(name, parent, ...)`: Create a new class.
+* `TR_EXTENDS(parent)`: Extend another class
 
 #### function-like macros - class information ####
 
-* **TR\_GET\_CLASS(object):** Get the class of the given object.
-* **TR\_HAS\_PARENT(class):** Check if the class extends another class.
-* **TR\_IS\_OBJECT(obj):** Check that the given pointer is really an
+* `TR_GET_CLASS(object)`: Get the class of the given object.
+* `TR_HAS_PARENT(class)`: Check if the class extends another class.
+* `TR_IS_OBJECT(obj)`: Check that the given pointer is really an
   instance of a class.
-* **TR\_INSTANCE\_OF(class, obj):** Check that the given obj is an instance of
+* `TR_INSTANCE_OF(class, obj)`: Check that the given obj is an instance of
   class.
 
 #### function-like macros - interface selector helper ####
 
-* **TR\_CALL(object, iface, method, ...):** Call the interface implementation
+* `TR_CALL(object, iface, method, ...)`: Call the interface implementation
   of the class or one of the parent classes of object.
-* **TR\_RETCALL(object, iface, method, ret, ...):** Same as TR\_CALL but
+* `TR_RETCALL(object, iface, method, ret, ...)`: Same as TR\_CALL but
   with return value.
-* **TR\_PARENTCALL(object, iface, method, ...):** Directly call the
+* `TR_PARENTCALL(object, iface, method, ...)`: Directly call the
   implementation within the parent class.
 
 #### function-like macros - interface creation ####
 
-* **TR\_INTERFACE(name):**
-* **TR\_CREATE_INTERFACE(name, nfunc):**
-* **TR\_IF(name):**
-* **TR\_INIT\_IFACE(name, ...):**
+* `TR_INTERFACE(name)`: Declare a new inerface.
+* `TR_CREATE_INTERFACE(name, nfunc)`: Create the new interface.
+* `TR_INIT_IFACE(name, ...)`: Create an interface implementation and assign
+  functions to it.
+* `TR_IF(name)`: Convenience for getting an interface implementation by name.
+  Used when assigning an interface to a class.
+
+#### function-like macros for the class interface ####
+The valious constructor and destructors are also assigned to an interface. The
+is the only interface every class MUST have so that instances can be created and
+destroyed. At least a constructor and a destructor must be assigned to this 
+interface. The following selectors then utilize the interface to create and
+destroy instances.
+
+* `TR_new(class, ...)`: Create a new instance of a class with a variable
+  argument list for the constructor interface.
+* `TR_newv(class, args)`: Same as *TR_new* but accepts a va_list* for the
+  constructor arguments.
+* `TR_delete(object)`: Destroy an instance.
+* `TR_clone(object)`: Call an constructor that accepts another instance to
+  create a clone from this instance.
+
+#### selector functions subject/observer interface ####
+These are in fact two interfaces that can be used to implement the
+subject/observer design pattern.
+
+* `TR_subjectAttach(Subject, Observer)`: Add an observer to a subject. The
+  concrete implementation has to take care of memory management etc.
+* `TR_subjectDetach(Subject, Observer)`: Remove an observer from a subject.
+* `TR_notify(Subject):* Notify all registered observer of an event.
+* `TR_observerUpdate(Observer, Subject)`: This must be called in
+  TR_subjectNotify to inform a registered observer of an event.
+
+#### selector functions indexable interface ####
+
+* `TR_getIndex(Indexable)`: Get a unique index of an instance. How this is
+  created is subject of the concrete implementation.
+
+#### selector functions ####
+
+* `TR_serializedSize(Serializable)`: Get the size of the serialized instance.
+* `TR_serialize(Serializable, unsigned char * serialized)`: Serialize the
+  instance into the serialized buffer. The buffer has to be large enough to
+  hold the serialized instance.
+* `TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)`:
+  Initialize the instance with the serialized data stored in serialized.
+
+#### memory management - functions ####
+
+* `void * TR_malloc(size_t)`:
+* `void * TR_calloc(size_t, size_t)`:
+* `void * TR_reference(void *)`:
+* `size_t TR_getSize(void *)`:
+* `void TR_cleanup()`:
+
+#### memory management - macros ####
+
+* `TR_MEM_FREE(seg)`:
+
 
 ### EXAMPLE ###