gmio_stl: more doc

src/gmio_stl/stl_global.h

@@ -29,11 +29,19 @@
 #    define GMIO_LIBSTL_EXPORT GMIO_DECL_IMPORT
 #  endif /* GMIO_DATAX_LIBSTL_MAKE_DLL */
 #else
+/*! Expands either to GMIO_DECL_EXPORT or GMIO_DECL_IMPORT when respectively
+ *  compiling/using the DLL */
 #   define GMIO_LIBSTL_EXPORT
 #endif /* GMIO_LIBSTL_DLL */
 
-/* STLB */
+/*! Constants for the STL binary format */
-enum { GMIO_STLB_HEADER_SIZE = 80 };
+enum {
-enum { GMIO_STLB_MIN_CONTENTS_SIZE = 284 };
+    /*! Size(in bytes) of the header data for STL binary */
+    GMIO_STLB_HEADER_SIZE = 80,
+
+    /*! Size(in bytes) of the minimum contents possible with the STL binary
+     *  format */
+    GMIO_STLB_MIN_CONTENTS_SIZE = 284
+};
 
 #endif /* GMIO_LIBSTL_GLOBAL_H */

src/gmio_stl/stl_io.h

@@ -46,8 +46,7 @@ struct gmio_stla_read_options
      *  \p stream_size is passed to gmio_transfer::handle_progress_func() as
      *  the \p max_value argument.
      *
-     *  It's defaulted to \c 0 if options argument is set to NULL (when
+     *  Defaulted to \c 0 when calling gmio_stla_read() with \c options==NULL
-     *  calling gmio_stla_read())
      */
     size_t stream_size;
 };
@@ -55,20 +54,34 @@ typedef struct gmio_stla_read_options  gmio_stla_read_options_t;
 
 /*! Reads geometry from STL ascii stream
  *
- *  \p options should be always set to NULL (not used for the moment)
+ *  \param mesh Defines the callbacks for the mesh creation
+ *  \param trsf Defines needed objects for the read operation
+ *  \param options Options for the operation, can be \c NULL to use default
+ *                 values
+ *
+ *  \return Error code (see error.h and stl_error.h)
  */
 GMIO_LIBSTL_EXPORT
 int gmio_stla_read(gmio_stl_mesh_creator_t* creator,
                    gmio_transfer_t* trsf,
                    const gmio_stla_read_options_t* options);
 
+
 /*! Options for gmio_stla_write() */
 struct gmio_stla_write_options
 {
-    /*! May be NULL to generate default name */
+    /*! Name of the solid to appear in "solid <name> \n facet normal ..."
+     *
+     * Defaulted to an empty string "" when :
+     *    \li calling gmio_stla_write() with <tt>options == NULL</tt>
+     *    \li OR <tt>solid_name == NULL</tt>
+     */
     const char* solid_name;
 
-    /*! The maximum number of significant digits(set to 9 if options == NULL) */
+    /*! The maximum number of significant digits to write float values
+     *
+     *  Defaulted to \c 9 when calling gmio_stla_write() with \c options==NULL
+     */
     uint8_t     float32_prec;
 };
 typedef struct gmio_stla_write_options  gmio_stla_write_options_t;
@@ -76,13 +89,12 @@ typedef struct gmio_stla_write_options  gmio_stla_write_options_t;
 /*! Writes geometry in the STL ascii format
  *
  *  \param mesh Defines the mesh to write
- *  \param trsf Defines needed objects (stream, buffer, ...) for the writing
+ *  \param trsf Defines needed objects for the write operation
- *              operation
+ *  \param options Options for the operation, can be \c NULL to use default
- *  \param options Options for the writing operation, can be set to NULL to
+ *                 values
- *                 use default values
  *
- *  \return Error code
+ *  \return Error code (see error.h and stl_error.h)
- *  \retval GMIO_NO_ERROR If operation successful
+ *  \retval GMIO_INVALID_BUFFER_SIZE_ERROR if \c trs->buffer_size < 512
  */
 GMIO_LIBSTL_EXPORT
 int gmio_stla_write(const gmio_stl_mesh_t* mesh,
@@ -96,12 +108,26 @@ int gmio_stla_write(const gmio_stl_mesh_t* mesh,
 /*! Options for gmio_stlb_read() */
 struct gmio_stlb_read_options
 {
-    /*! Set to host byte order if not specified (ie. options == NULL) */
+    /*! Byte order of the input STL binary data
+     *
+     *  Defaulted to host's endianness when calling gmio_stlb_read()
+     *  with \c options==NULL
+     */
     gmio_endianness_t byte_order;
 };
 typedef struct gmio_stlb_read_options  gmio_stlb_read_options_t;
 
-/*! Reads geometry from STL binary stream */
+/*! Reads geometry from STL binary stream
+ *
+ *  \param mesh Defines the callbacks for the mesh creation
+ *  \param trsf Defines needed objects for the read operation
+ *  \param options Options for the operation, can be \c NULL to use default
+ *                 values
+ *
+ *  \return Error code (see error.h and stl_error.h)
+ *  \retval GMIO_INVALID_BUFFER_SIZE_ERRO
+ *          if \c trs->buffer_size < GMIO_STLB_MIN_CONTENTS_SIZE
+ */
 GMIO_LIBSTL_EXPORT
 int gmio_stlb_read(gmio_stl_mesh_creator_t* creator,
                    gmio_transfer_t* trsf,
@@ -111,15 +137,34 @@ int gmio_stlb_read(gmio_stl_mesh_creator_t* creator,
 /*! Options for gmio_stlb_write() */
 struct gmio_stlb_write_options
 {
-    /*! Header data consisting of 80 bytes */
+    /*! Header data consisting of 80 bytes
+     *
+     *  Defaulted to an array containing 0 when :
+     *    \li calling gmio_stlb_write() with <tt>options == NULL</tt>
+     *    \li OR <tt>header_data == NULL</tt>
+     */
     const uint8_t* header_data;
 
-    /*! Set to host byte order if not specified (ie. options == NULL) */
+    /*! Byte order of the output STL binary data
+     *
+     *  Defaulted to host's endianness when calling gmio_stlb_write()
+     *  with \c options==NULL
+     */
     gmio_endianness_t byte_order;
 };
 typedef struct gmio_stlb_write_options  gmio_stlb_write_options_t;
 
-/*! Writes geometry in the STL binary format */
+/*! Writes geometry in the STL binary format
+ *
+ *  \param mesh Defines the mesh to write
+ *  \param trsf Defines needed objects for the write operation
+ *  \param options Options for the operation, can be \c NULL to use default
+ *                 values
+ *
+ *  \return Error code (see error.h and stl_error.h)
+ *  \retval GMIO_INVALID_BUFFER_SIZE_ERRO
+ *          if \c trs->buffer_size < GMIO_STLB_MIN_CONTENTS_SIZE
+ */
 GMIO_LIBSTL_EXPORT
 int gmio_stlb_write(const gmio_stl_mesh_t* mesh,
                     gmio_transfer_t* trsf,

src/gmio_stl/stl_triangle.h

@@ -37,22 +37,25 @@ typedef struct gmio_stl_coords gmio_stl_coords_t;
  *  orientation(normal) */
 struct gmio_stl_triangle
 {
-    gmio_stl_coords_t normal;
+    gmio_stl_coords_t normal; /*!< Normal vector */
-    gmio_stl_coords_t v1;
+    gmio_stl_coords_t v1; /*!< Vertex 1 */
-    gmio_stl_coords_t v2;
+    gmio_stl_coords_t v2; /*!< Vertex 2 */
-    gmio_stl_coords_t v3;
+    gmio_stl_coords_t v3; /*!< Vertex 3 */
     uint16_t attribute_byte_count; /*!< Useful only for STL binary format */
 };
 
 typedef struct gmio_stl_triangle gmio_stl_triangle_t;
 
+/*! Constants for STL triangles */
+enum {
     /*! Compact size of a gmio_stl_coords_t object */
-enum { GMIO_STL_COORDS_RAWSIZE = (3 * sizeof(gmio_float32_t)) };
+    GMIO_STL_COORDS_RAWSIZE = (3 * sizeof(gmio_float32_t)),
 
     /*! Compact size of a gmio_stl_triangle_t object for STL ascii format */
-enum { GMIO_STLA_TRIANGLE_RAWSIZE = (4 * GMIO_STL_COORDS_RAWSIZE) };
+    GMIO_STLA_TRIANGLE_RAWSIZE = (4 * GMIO_STL_COORDS_RAWSIZE),
 
     /*! Compact size of a gmio_stl_triangle_t object for STL binary format */
-enum { GMIO_STLB_TRIANGLE_RAWSIZE = (GMIO_STLA_TRIANGLE_RAWSIZE + sizeof(uint16_t)) };
+    GMIO_STLB_TRIANGLE_RAWSIZE = (GMIO_STLA_TRIANGLE_RAWSIZE + sizeof(uint16_t))
+};
 
 #endif /* GMIO_LIBSTL_TRIANGLE_H */