Add more doc

src/libstl/stl_error.h

@@ -1,20 +1,32 @@
 #ifndef FOUG_LIBSTL_STL_ERROR_H
 #define FOUG_LIBSTL_STL_ERROR_H
 
+/*! A byte-mask to tag(identify) STL-specific error codes */
 #define FOUG_STL_ERROR_TAG  0x11000000
 
+/*! This enum defines the various error codes reported by STL read/write functions */
 enum foug_stl_rw_error
 {
   /*! Common STL write error indicating foug_stl_geom::get_triangle_func() pointer is NULL */
   FOUG_STL_WRITE_NULL_GET_TRIANGLE_FUNC_ERROR = FOUG_STL_ERROR_TAG + 1,
 
   /* Specific error codes returned by STL_ascii read function */
+
+  /*! Parsing error occured in foug_stla_read() due to malformed STL ascii input */
   FOUG_STLA_READ_PARSE_ERROR = FOUG_STL_ERROR_TAG + 100,
+
+  /*! Invalid max number of decimal significants digits for foug_stla_write(), must be in [1..9] */
   FOUG_STLA_WRITE_INVALID_REAL32_PREC_ERROR = FOUG_STL_ERROR_TAG + 101,
 
   /* Specific error codes returned by STL_binary read/write functions */
+
+  /*! The byte order argument supplied is not supported, must be little or big endian */
   FOUG_STLB_UNSUPPORTED_BYTE_ORDER_ERROR = FOUG_STL_ERROR_TAG + 300,
+
+  /*! Error occured when reading header data in foug_stlb_read() */
   FOUG_STLB_READ_HEADER_WRONG_SIZE_ERROR = FOUG_STL_ERROR_TAG + 301,
+
+  /*! Error occured when reading facet count in foug_stlb_read() */
   FOUG_STLB_READ_FACET_COUNT_ERROR = FOUG_STL_ERROR_TAG + 302
 };
 

src/libstl/stl_geom.h

@@ -4,11 +4,17 @@
 #include "stl_global.h"
 #include "stl_triangle.h"
 
+/*! Provides an interface for accessing the underlying(hidden) user mesh */
 struct foug_stl_geom
 {
+  /*! Opaque pointer on the user mesh, passed as first argument to hook functions */
   const void* cookie;
+
+  /*! Number of triangles in the mesh */
   uint32_t    triangle_count;
-  void      (*get_triangle_func)(const void*, uint32_t, foug_stl_triangle_t*);
+
+  /*! Pointer on a function that stores the mesh triangle of index \p tri_id into \p triangle */
+  void      (*get_triangle_func)(const void* cookie, uint32_t tri_id, foug_stl_triangle_t* triangle);
 };
 
 typedef struct foug_stl_geom foug_stl_geom_t;

src/libstl/stl_geom_creator.h

@@ -4,16 +4,43 @@
 #include "stl_global.h"
 #include "stl_triangle.h"
 
+/*! Provides an interface for the creation of the underlying(hidden) user mesh */
 struct foug_stl_geom_creator
 {
+  /*! Opaque pointer on the user mesh, passed as first argument to hook functions */
   void* cookie;
 
-  void (*ascii_begin_solid_func)(void*, const char*); /* Optional */
+  /* All function pointers are optional (ie can be set to NULL) */
-  void (*binary_begin_solid_func)(void*, uint32_t, const uint8_t*); /* Optional */
 
-  void (*add_triangle_func)(void*, uint32_t, const foug_stl_triangle_t*); /* Optional */
+  /*! Pointer on a function that handles declaration of a solid of name \p solid_name .
+   *
+   *  This optional function is useful only with STL ascii (ie. foug_stla_read())
+   */
+  void (*ascii_begin_solid_func)(void* cookie, const char* solid_name);
 
-  void (*end_solid_func)       (void*); /* Optional */
+  /*! Pointer on a function that handles declaration of a mesh with \p tri_count number of triangles.
+   *
+   *  This optional function is useful only with STL binary (ie. foug_stlb_read()).
+   *
+   *  The argument \p header contains the header data(80 bytes)
+   */
+  void (*binary_begin_solid_func)(void* cookie, uint32_t tri_count, const uint8_t* header);
+
+  /*! Pointer on a function that adds a triangle to the user mesh.
+   *
+   *  The argument \p triangle is the triangle to be added, note that
+   *  foug_stl_triangle_t::attribute_byte_count is meaningless for STL ascii.
+   *
+   *  The argument \p tri_id is the index of the mesh triangle
+   */
+  void (*add_triangle_func)(void* cookie, uint32_t tri_id, const foug_stl_triangle_t* triangle);
+
+  /*! Pointer on a function that finalizes creation of the user mesh.
+   *
+   *  This optional function is called at the end of the read process, ie. after all triangles have
+   *  been added
+   */
+  void (*end_solid_func)(void* cookie);
 };
 
 typedef struct foug_stl_geom_creator foug_stl_geom_creator_t;

src/libstl/stl_triangle.h

@@ -3,6 +3,7 @@
 
 #include "stl_global.h"
 
+/*! Cartesian coordinate entity in 3D space, specifically tailored for STL needs (single-float) */
 struct foug_stl_coords
 {
   foug_real32_t x;
@@ -11,19 +12,26 @@ struct foug_stl_coords
 };
 
 typedef struct foug_stl_coords foug_stl_coords_t;
-#define FOUG_STL_COORDS_RAWSIZE (3 * sizeof(foug_real32_t))
 
+/*! STL mesh triangle defined three geometric vertices and an orientation(normal) */
 struct foug_stl_triangle
 {
   foug_stl_coords_t normal;
   foug_stl_coords_t v1;
   foug_stl_coords_t v2;
   foug_stl_coords_t v3;
-  uint16_t          attribute_byte_count; /* Useful only for STL binary format */
+  uint16_t          attribute_byte_count; /*!< Useful only for STL binary format */
 };
 
 typedef struct foug_stl_triangle foug_stl_triangle_t;
+
+/*! Compact size of a foug_stl_coords_t object */
+#define FOUG_STL_COORDS_RAWSIZE (3 * sizeof(foug_real32_t))
+
+/*! Compact size of a foug_stl_triangle_t object for STL ascii format */
 #define FOUG_STLA_TRIANGLE_RAWSIZE (4 * FOUG_STL_COORDS_RAWSIZE)
+
+/*! Compact size of a foug_stl_triangle_t object for STL binary format */
 #define FOUG_STLB_TRIANGLE_RAWSIZE (FOUG_STLA_TRIANGLE_RAWSIZE + sizeof(uint16_t))
 
 #endif /* FOUG_DATAX_C_LIBSTL_TRIANGLE_H */

src/transfer.h

@@ -5,11 +5,19 @@
 #include "stream.h"
 #include "task_control.h"
 
+/*! Defines data required for any transfer(read/write) operation */
 struct foug_transfer
 {
+  /*! The stream to be used for I/O */
   foug_stream_t       stream;
+
+  /*! The optional control object used to handle progress of the transfer */
   foug_task_control_t task_control;
+
+  /*! Pointer on a user memory area used by the transfer as a buffer for stream optimization */
   void*               buffer;
+
+  /*! Size (in bytes) of the buffer memoru */
   size_t              buffer_size;
 };