Commit 378eeef412a25d7f8b8c784233ac0dae06c6f7f1

Authored by Georg Hopp
1 parent bc626249

more documentation

Showing 2 changed files with 132 additions and 33 deletions
@@ -32,37 +32,76 @@ @@ -32,37 +32,76 @@
32 <p>This can be installed via the usual configure, make, make install cycle. For gentoo users am ebuild is added under docs.</p> 32 <p>This can be installed via the usual configure, make, make install cycle. For gentoo users am ebuild is added under docs.</p>
33 <h3 id="api-doc">API DOC</h3> 33 <h3 id="api-doc">API DOC</h3>
34 <p>To generate the api doc a patched version of doxygen is neccessary. A patch is included under docs.</p> 34 <p>To generate the api doc a patched version of doxygen is neccessary. A patch is included under docs.</p>
35 -<p><em>make docs</em> creates the api doc.</p> 35 +<p><code>make docs</code> creates the api doc.</p>
36 <h3 id="test-coverage-report">TEST COVERAGE REPORT</h3> 36 <h3 id="test-coverage-report">TEST COVERAGE REPORT</h3>
37 <p>gcov and lcov are needed to build these.</p> 37 <p>gcov and lcov are needed to build these.</p>
38 -<p>The source has to be configured with <em>configure --enable-gcov</em>. <em>make coverage-html</em> creates the converage reports then.</p> 38 +<p>The source has to be configured with <code>configure --enable-gcov</code>. <code>make coverage-html</code> creates the converage reports then.</p>
39 <h2 id="usage">USAGE</h2> 39 <h2 id="usage">USAGE</h2>
40 <h3 id="api">API</h3> 40 <h3 id="api">API</h3>
  41 +<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>
41 <h4 id="function-like-macros---class-creation">function-like macros - class creation</h4> 42 <h4 id="function-like-macros---class-creation">function-like macros - class creation</h4>
42 <ul> 43 <ul>
43 -<li><strong>TR_CLASS(name):</strong> Declare a new class.</li>  
44 -<li><strong>TR_CREATE_CLASS(name, parent, ...):</strong> Create a new class.</li>  
45 -<li><strong>TR_EXTENDS(parent):</strong> Extend another class</li> 44 +<li><code>TR_CLASS(name)</code>: Declare a new class.</li>
  45 +<li><code>TR_CREATE_CLASS(name, parent, ...)</code>: Create a new class.</li>
  46 +<li><code>TR_EXTENDS(parent)</code>: Extend another class</li>
46 </ul> 47 </ul>
47 <h4 id="function-like-macros---class-information">function-like macros - class information</h4> 48 <h4 id="function-like-macros---class-information">function-like macros - class information</h4>
48 <ul> 49 <ul>
49 -<li><strong>TR_GET_CLASS(object):</strong> Get the class of the given object.</li>  
50 -<li><strong>TR_HAS_PARENT(class):</strong> Check if the class extends another class.</li>  
51 -<li><strong>TR_IS_OBJECT(obj):</strong> Check that the given pointer is really an instance of a class.</li>  
52 -<li><strong>TR_INSTANCE_OF(class, obj):</strong> Check that the given obj is an instance of class.</li> 50 +<li><code>TR_GET_CLASS(object)</code>: Get the class of the given object.</li>
  51 +<li><code>TR_HAS_PARENT(class)</code>: Check if the class extends another class.</li>
  52 +<li><code>TR_IS_OBJECT(obj)</code>: Check that the given pointer is really an instance of a class.</li>
  53 +<li><code>TR_INSTANCE_OF(class, obj)</code>: Check that the given obj is an instance of class.</li>
53 </ul> 54 </ul>
54 <h4 id="function-like-macros---interface-selector-helper">function-like macros - interface selector helper</h4> 55 <h4 id="function-like-macros---interface-selector-helper">function-like macros - interface selector helper</h4>
55 <ul> 56 <ul>
56 -<li><strong>TR_CALL(object, iface, method, ...):</strong> Call the interface implementation of the class or one of the parent classes of object.</li>  
57 -<li><strong>TR_RETCALL(object, iface, method, ret, ...):</strong> Same as TR_CALL but with return value.</li>  
58 -<li><strong>TR_PARENTCALL(object, iface, method, ...):</strong> Directly call the implementation within the parent class.</li> 57 +<li><code>TR_CALL(object, iface, method, ...)</code>: Call the interface implementation of the class or one of the parent classes of object.</li>
  58 +<li><code>TR_RETCALL(object, iface, method, ret, ...)</code>: Same as TR_CALL but with return value.</li>
  59 +<li><code>TR_PARENTCALL(object, iface, method, ...)</code>: Directly call the implementation within the parent class.</li>
59 </ul> 60 </ul>
60 <h4 id="function-like-macros---interface-creation">function-like macros - interface creation</h4> 61 <h4 id="function-like-macros---interface-creation">function-like macros - interface creation</h4>
61 <ul> 62 <ul>
62 -<li><strong>TR_INTERFACE(name):</strong></li>  
63 -<li><strong>TR_CREATE_INTERFACE(name, nfunc):</strong></li>  
64 -<li><strong>TR_IF(name):</strong></li>  
65 -<li><strong>TR_INIT_IFACE(name, ...):</strong></li> 63 +<li><code>TR_INTERFACE(name)</code>: Declare a new inerface.</li>
  64 +<li><code>TR_CREATE_INTERFACE(name, nfunc)</code>: Create the new interface.</li>
  65 +<li><code>TR_INIT_IFACE(name, ...)</code>: Create an interface implementation and assign functions to it.</li>
  66 +<li><code>TR_IF(name)</code>: Convenience for getting an interface implementation by name. Used when assigning an interface to a class.</li>
  67 +</ul>
  68 +<h4 id="function-like-macros-for-the-class-interface">function-like macros for the class interface</h4>
  69 +<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>
  70 +<ul>
  71 +<li><code>TR_new(class, ...)</code>: Create a new instance of a class with a variable argument list for the constructor interface.</li>
  72 +<li><code>TR_newv(class, args)</code>: Same as <em>TR_new</em> but accepts a va_list* for the constructor arguments.</li>
  73 +<li><code>TR_delete(object)</code>: Destroy an instance.</li>
  74 +<li><code>TR_clone(object)</code>: Call an constructor that accepts another instance to create a clone from this instance.</li>
  75 +</ul>
  76 +<h4 id="selector-functions-subjectobserver-interface">selector functions subject/observer interface</h4>
  77 +<p>These are in fact two interfaces that can be used to implement the subject/observer design pattern.</p>
  78 +<ul>
  79 +<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>
  80 +<li><code>TR_subjectDetach(Subject, Observer)</code>: Remove an observer from a subject.</li>
  81 +<li>`TR_notify(Subject):* Notify all registered observer of an event.</li>
  82 +<li><code>TR_observerUpdate(Observer, Subject)</code>: This must be called in TR_subjectNotify to inform a registered observer of an event.</li>
  83 +</ul>
  84 +<h4 id="selector-functions-indexable-interface">selector functions indexable interface</h4>
  85 +<ul>
  86 +<li><code>TR_getIndex(Indexable)</code>: Get a unique index of an instance. How this is created is subject of the concrete implementation.</li>
  87 +</ul>
  88 +<h4 id="selector-functions">selector functions</h4>
  89 +<ul>
  90 +<li><code>TR_serializedSize(Serializable)</code>: Get the size of the serialized instance.</li>
  91 +<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>
  92 +<li><code>TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)</code>: Initialize the instance with the serialized data stored in serialized.</li>
  93 +</ul>
  94 +<h4 id="memory-management---functions">memory management - functions</h4>
  95 +<ul>
  96 +<li><code>void * TR_malloc(size_t)</code>:</li>
  97 +<li><code>void * TR_calloc(size_t, size_t)</code>:</li>
  98 +<li><code>void * TR_reference(void *)</code>:</li>
  99 +<li><code>size_t TR_getSize(void *)</code>:</li>
  100 +<li><code>void TR_cleanup()</code>:</li>
  101 +</ul>
  102 +<h4 id="memory-management---macros">memory management - macros</h4>
  103 +<ul>
  104 +<li><code>TR_MEM_FREE(seg)</code>:</li>
66 </ul> 105 </ul>
67 <h3 id="example">EXAMPLE</h3> 106 <h3 id="example">EXAMPLE</h3>
68 <h4 id="optimized-memory-management">optimized memory management</h4> 107 <h4 id="optimized-memory-management">optimized memory management</h4>
@@ -76,14 +76,14 @@ cycle. For gentoo users am ebuild is added under docs. @@ -76,14 +76,14 @@ cycle. For gentoo users am ebuild is added under docs.
76 To generate the api doc a patched version of doxygen is 76 To generate the api doc a patched version of doxygen is
77 neccessary. A patch is included under docs. 77 neccessary. A patch is included under docs.
78 78
79 -*make docs* creates the api doc. 79 +`make docs` creates the api doc.
80 80
81 ### TEST COVERAGE REPORT 81 ### TEST COVERAGE REPORT
82 82
83 gcov and lcov are needed to build these. 83 gcov and lcov are needed to build these.
84 84
85 -The source has to be configured with *configure --enable-gcov*.  
86 -*make coverage-html* creates the converage reports then. 85 +The source has to be configured with `configure --enable-gcov`.
  86 +`make coverage-html` creates the converage reports then.
87 87
88 88
89 USAGE 89 USAGE
@@ -91,36 +91,96 @@ USAGE @@ -91,36 +91,96 @@ USAGE
91 91
92 ### API ### 92 ### API ###
93 93
  94 +The public API consists of several preprocessor macros and some functions.
  95 +When you look through the code you will find other symbols (functions or
  96 +macros) which might seem useful. Here I try to focus on the neccessaties
  97 +for using the library.
  98 +
94 #### function-like macros - class creation #### 99 #### function-like macros - class creation ####
95 100
96 -* **TR\_CLASS(name):** Declare a new class.  
97 -* **TR\_CREATE\_CLASS(name, parent, ...):** Create a new class.  
98 -* **TR\_EXTENDS(parent):** Extend another class 101 +* `TR_CLASS(name)`: Declare a new class.
  102 +* `TR_CREATE_CLASS(name, parent, ...)`: Create a new class.
  103 +* `TR_EXTENDS(parent)`: Extend another class
99 104
100 #### function-like macros - class information #### 105 #### function-like macros - class information ####
101 106
102 -* **TR\_GET\_CLASS(object):** Get the class of the given object.  
103 -* **TR\_HAS\_PARENT(class):** Check if the class extends another class.  
104 -* **TR\_IS\_OBJECT(obj):** Check that the given pointer is really an 107 +* `TR_GET_CLASS(object)`: Get the class of the given object.
  108 +* `TR_HAS_PARENT(class)`: Check if the class extends another class.
  109 +* `TR_IS_OBJECT(obj)`: Check that the given pointer is really an
105 instance of a class. 110 instance of a class.
106 -* **TR\_INSTANCE\_OF(class, obj):** Check that the given obj is an instance of 111 +* `TR_INSTANCE_OF(class, obj)`: Check that the given obj is an instance of
107 class. 112 class.
108 113
109 #### function-like macros - interface selector helper #### 114 #### function-like macros - interface selector helper ####
110 115
111 -* **TR\_CALL(object, iface, method, ...):** Call the interface implementation 116 +* `TR_CALL(object, iface, method, ...)`: Call the interface implementation
112 of the class or one of the parent classes of object. 117 of the class or one of the parent classes of object.
113 -* **TR\_RETCALL(object, iface, method, ret, ...):** Same as TR\_CALL but 118 +* `TR_RETCALL(object, iface, method, ret, ...)`: Same as TR\_CALL but
114 with return value. 119 with return value.
115 -* **TR\_PARENTCALL(object, iface, method, ...):** Directly call the 120 +* `TR_PARENTCALL(object, iface, method, ...)`: Directly call the
116 implementation within the parent class. 121 implementation within the parent class.
117 122
118 #### function-like macros - interface creation #### 123 #### function-like macros - interface creation ####
119 124
120 -* **TR\_INTERFACE(name):**  
121 -* **TR\_CREATE_INTERFACE(name, nfunc):**  
122 -* **TR\_IF(name):**  
123 -* **TR\_INIT\_IFACE(name, ...):** 125 +* `TR_INTERFACE(name)`: Declare a new inerface.
  126 +* `TR_CREATE_INTERFACE(name, nfunc)`: Create the new interface.
  127 +* `TR_INIT_IFACE(name, ...)`: Create an interface implementation and assign
  128 + functions to it.
  129 +* `TR_IF(name)`: Convenience for getting an interface implementation by name.
  130 + Used when assigning an interface to a class.
  131 +
  132 +#### function-like macros for the class interface ####
  133 +The valious constructor and destructors are also assigned to an interface. The
  134 +is the only interface every class MUST have so that instances can be created and
  135 +destroyed. At least a constructor and a destructor must be assigned to this
  136 +interface. The following selectors then utilize the interface to create and
  137 +destroy instances.
  138 +
  139 +* `TR_new(class, ...)`: Create a new instance of a class with a variable
  140 + argument list for the constructor interface.
  141 +* `TR_newv(class, args)`: Same as *TR_new* but accepts a va_list* for the
  142 + constructor arguments.
  143 +* `TR_delete(object)`: Destroy an instance.
  144 +* `TR_clone(object)`: Call an constructor that accepts another instance to
  145 + create a clone from this instance.
  146 +
  147 +#### selector functions subject/observer interface ####
  148 +These are in fact two interfaces that can be used to implement the
  149 +subject/observer design pattern.
  150 +
  151 +* `TR_subjectAttach(Subject, Observer)`: Add an observer to a subject. The
  152 + concrete implementation has to take care of memory management etc.
  153 +* `TR_subjectDetach(Subject, Observer)`: Remove an observer from a subject.
  154 +* `TR_notify(Subject):* Notify all registered observer of an event.
  155 +* `TR_observerUpdate(Observer, Subject)`: This must be called in
  156 + TR_subjectNotify to inform a registered observer of an event.
  157 +
  158 +#### selector functions indexable interface ####
  159 +
  160 +* `TR_getIndex(Indexable)`: Get a unique index of an instance. How this is
  161 + created is subject of the concrete implementation.
  162 +
  163 +#### selector functions ####
  164 +
  165 +* `TR_serializedSize(Serializable)`: Get the size of the serialized instance.
  166 +* `TR_serialize(Serializable, unsigned char * serialized)`: Serialize the
  167 + instance into the serialized buffer. The buffer has to be large enough to
  168 + hold the serialized instance.
  169 +* `TR_unserialize(Serializable, const unsigned char * serialized, size_t ssize)`:
  170 + Initialize the instance with the serialized data stored in serialized.
  171 +
  172 +#### memory management - functions ####
  173 +
  174 +* `void * TR_malloc(size_t)`:
  175 +* `void * TR_calloc(size_t, size_t)`:
  176 +* `void * TR_reference(void *)`:
  177 +* `size_t TR_getSize(void *)`:
  178 +* `void TR_cleanup()`:
  179 +
  180 +#### memory management - macros ####
  181 +
  182 +* `TR_MEM_FREE(seg)`:
  183 +
124 184
125 ### EXAMPLE ### 185 ### EXAMPLE ###
126 186
Please register or login to post a comment