explain why I hate doxygen so much tonight, and go have a decent sleep

[simgrid.git] / include / gras / datadesc.h

diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h
index 7181a7c..23dfa4c 100644 (file)
--- a/include/gras/datadesc.h
+++ b/include/gras/datadesc.h
@@ -24,6 +24,14 @@ BEGIN_DECL()
  * 
  * There is several possible interfaces for this, ranging from the really completely automatic parsing to 
  * completely manual. Let's study each of them from the simplest to the more advanced.
+ * 
+ * \warning At least, I would like to present those sections in the right order, but doxygen prevents me 
+ * from doing so. There is a weird bug I fail to circumvent here. The right order is naturally:
+ *   - a) basic operations
+ *   - b) Automatic parsing
+ *   - c) Simple manual definitions
+ *   - d) Callback Persistant State: Simple push/pop mecanism
+ *   - e) Callback Persistant State: Full featured mecanism
  */
   
 /** @name a) basic operations
@@ -40,7 +48,7 @@ BEGIN_DECL()
  gras_datadesc_type_t uc = gras_datadesc_by_name("unsigned char");
  gras_datadesc_type_t str = gras_datadesc_by_name("string");\endverbatim
  */
-/** @{ */
+/* @{ */
   
 /** @brief Opaque type describing a type description. */
 typedef struct s_gras_datadesc_type *gras_datadesc_type_t;
@@ -48,15 +56,8 @@ typedef struct s_gras_datadesc_type *gras_datadesc_type_t;
 /** \brief Search a type description from its name */
 gras_datadesc_type_t gras_datadesc_by_name(const char *name);
 
-
-/** @} */
-  
-/** @fn gras_datadesc_type_t gras_datadesc_parse(const char *name, const char *C_statement) 
- *  @ingroup GRAS_dd_implem 
- *
- *  Helper function doing the crude job of type parsing.
- */
-  
+/* @} */
+    
 /** @name b) Automatic parsing
  *  @ingroup GRAS_dd
  * 
@@ -104,12 +105,9 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name);
 /** @{ */
 
  
-/**   @def GRAS_DEFINE_TYPE
+/**   @brief Automatically parse C code
  *    @hideinitializer
- *    @brief Automatically parse C code
  */
-  
-
 #define GRAS_DEFINE_TYPE(name,def) \
   static const char * _gras_this_type_symbol_does_not_exist__##name=#def; def
  
@@ -274,11 +272,27 @@ int gras_datadesc_get_id(gras_datadesc_type_t ddt);
 
 /*@}*/
 
-/** @name Callback Persistant State: Simple push/pop mecanism
+/** @name d) Callback Persistant State: Simple push/pop mecanism
  *  @ingroup GRAS_dd
  * 
  * Sometimes, one of the callbacks need to leave information for the next ones. If this is a simple integer (such as
  * an array size), you can use the functions described here. If not, you'll have to play with the complete cbps interface.
+ * 
+ * Here is an example:\verbatim
+struct s_array {
+  int length;
+  int *data;
+}
+[...]
+my_type=gras_datadesc_struct("s_array");
+gras_datadesc_struct_append(my_type,"length", gras_datadesc_by_name("int"));
+gras_datadesc_cb_field_send (my_type, "length", gras_datadesc_cb_push_int);
+
+gras_datadesc_struct_append(my_type,"data",
+                            gras_datadesc_array_dyn ("s_array::data",gras_datadesc_by_name("int"), gras_datadesc_cb_pop));
+gras_datadesc_struct_close(my_type);
+\endverbatim
+
  */
 /*@{*/
 
@@ -296,7 +310,7 @@ void gras_datadesc_cb_push_ulint(gras_cbps_t vars, void *data);
 
 /*@}*/
 
-/** @name Callback Persistant State: Full featured mecanism
+/** @name e) Callback Persistant State: Full featured mecanism
  *  @ingroup GRAS_dd
  * 
  * Sometimes, one of the callbacks need to leave information for the next ones. If the simple push/pop mecanism