Improve doc

README.md

@@ -32,25 +32,9 @@ Main highlights:
 Supported CAD files format
 ==========================
 
-Current version only supports the STL file format (STereoLithography), but
+Current version only supports the STL file format(STereoLithography) but
-support is complete :
+support is complete, see module
-
+[gmio_stl](http://www.fougue.pro/docs/gmio/group__gmio__stl.html#details)
-  * [x] ASCII format: Case-insensitive reading
-  * [x] ASCII format: Output format(%f, %e, ...) and precision of floats support
-  * [x] Binary format: Little/big endian support
-  * [x] Binary format: 80-byte header and facet "attribute byte count" support
-  * [x] Detection of the input format
-  * [x] Retrieval of infomations about contents(facet count, solid name, ...)
-  * [x] Multiple solids from stream(eg. 4 solids in STL ascii file)
-
-In addition, the STL module has the following advatanges:
-
-  * [x] The user keeps its own geometry data structures, no mesh conversion needed
-  * [x] Fixed memory consumption and independant of the mesh size
-  * [x] Seamless use of OpenCascade
-        [StlMesh_Mesh](http://dev.opencascade.org/doc/refman/html/class_stl_mesh___mesh.html)
-        and [MeshVS_DataSource](http://dev.opencascade.org/doc/refman/html/class_mesh_v_s___data_source.html)
-        in gmio
 
 
 Building gmio

doc/Doxyfile.cmake

@@ -674,7 +674,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is 
 # run.
 
-EXCLUDE                =
+EXCLUDE                = @CMAKE_CURRENT_SOURCE_DIR@/../src/gmio_support/stl_occ_utils.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or 
 # directories that are symbolic links (a Unix file system feature) are excluded 

doc/mainpage.dox

@@ -17,23 +17,8 @@
 
 \section sup_cadf Supported CAD files format
 
-Current version only supports the STL file format (STereoLithography), but
+Current version only supports the STL file format(STereoLithography) but
-support is complete :
+support is complete, see module \ref gmio_stl
-
-  \li ASCII format: Case-insensitive reading
-  \li ASCII format: Output format(\%f, \%e, ...) and precision of floats support
-  \li Binary format: Little/big endian support
-  \li Binary format: 80-byte header and facet "attribute byte count" support
-  \li Detection of the input format
-  \li Retrieval of infomations about contents(facet count, solid name, ...)
-  \li Multiple solids from stream(eg. 4 solids in STL ascii file)
-
-In addition, the STL module has the following advatanges:
-
-  \li The user keeps its own geometry data structures, no conversion needed
-  \li Fixed memory consumption and independant of the mesh size
-  \li Seamless use of OpenCascade \c StlMesh_Mesh and \c MeshVS_DataSource in
-      gmio(see \c gmio_support)
 
 \section build Building gmio
 

src/gmio_core/memblock.h

@@ -27,7 +27,21 @@
 
 #include <stddef.h>
 
-/*! Basic memory block */
+/*! Basic memory block
+ *
+ *  gmio_memblock comes with convenient constructors that binds to
+ *  <tt><stdlib.h></tt> allocation functions, like gmio_memblock_malloc(), ...
+ *
+ *  Binding gmio_memblock to some statically-allocated memory is done through
+ *  gmio_memblock() :
+ *  \code{.c}
+ *      char buff[512] = {};
+ *      struct gmio_memblock blk =
+ *                  gmio_memblock(buff, GMIO_ARRAY_SIZE(buff), NULL);
+ *  \endcode
+ *
+ *  Any gmio_memblock object can be safely freed with gmio_memblock_deallocate()
+ */
 struct gmio_memblock
 {
     /*! Pointer to the beginning of the memory block */
@@ -37,7 +51,10 @@ struct gmio_memblock
     size_t size;
 
     /*! Optional pointer on a function that deallocates the memory block
-     *  beginning at \p ptr */
+     *  beginning at \p ptr
+     *
+     *  \sa gmio_memblock_deallocate()
+     */
     void (*func_deallocate)(void* ptr);
 };
 
@@ -53,13 +70,22 @@ GMIO_API bool gmio_memblock_isnull(const struct gmio_memblock* mblock);
 GMIO_API struct gmio_memblock gmio_memblock(
                 void* ptr, size_t size, void (*func_deallocate)(void*));
 
-/*! Returns a gmio_memblock object allocated with standard \c malloc() */
+/*! Returns a gmio_memblock object allocated with standard \c malloc()
+ *
+ *  gmio_memblock::func_deallocate is set to standard \c free()
+ */
 GMIO_API struct gmio_memblock gmio_memblock_malloc(size_t size);
 
-/*! Returns a gmio_memblock object allocated with standard \c calloc() */
+/*! Returns a gmio_memblock object allocated with standard \c calloc()
+ *
+ *  gmio_memblock::func_deallocate is set to standard \c free()
+ */
 GMIO_API struct gmio_memblock gmio_memblock_calloc(size_t num, size_t size);
 
-/*! Returns a gmio_memblock object allocated with standard \c realloc() */
+/*! Returns a gmio_memblock object allocated with standard \c realloc()
+ *
+ *  gmio_memblock::func_deallocate is set to standard \c free()
+ */
 GMIO_API struct gmio_memblock gmio_memblock_realloc(void* ptr, size_t size);
 
 /*! Safe and convenient call to gmio_memblock::func_deallocate() */
@@ -75,7 +101,7 @@ typedef struct gmio_memblock (*gmio_memblock_constructor_func_t)();
 /*! Installs a global function to construct gmio_memblock objects
  *
  *  The constructor function allocates a gmio_memblock object on demand, to be
- *  used when a temporary mblock is needed.
+ *  used when a temporary memblock is needed.
  *
  *  This function is not thread-safe.
  */

src/gmio_stl/stl_global.h

@@ -20,21 +20,19 @@
  *  Provides API to handle input/output operations with the STL file format
  *
  *  Support of the STL file format(STereoLithography) is complete :
- *
  *  \li ASCII format: Case-insensitive reading
- *  \li ASCII format: Output format(\%f, \%e, ...) and precision of floats support
+ *  \li ASCII format: Support of output format(<tt>\%f</tt>, <tt>\%e</tt>, ...)
- *  \li Binary format: Little/big endian support
+ *      and precision of floats
- *  \li Binary format: 80-byte header and facet "attribute byte count" support
+ *  \li Binary format: Support of little/big endian
+ *  \li Binary format: Support of 80-byte header and facet "attribute byte count"
+ *  \li Support of multiple solids from stream(eg. 4 solids in STL ascii file)
  *  \li Detection of the input format
- *  \li Retrieval of infomations about contents(facet count, solid name, ...)
+ *  \li Retrieval of infomations about contents
- *  \li Multiple solids from stream(eg. 4 solids in STL ascii file)
  *
  *  In addition, the gmioSTL module has the following advatanges:
- *
+ *  \li The user keeps its own geometry data structures, no conversion needed.
- *  \li The user keeps its own geometry data structures, no conversion needed
  *  \li Fixed memory consumption and independant of the mesh size
- *  \li Seamless use of OpenCascade \c StlMesh_Mesh and \c MeshVS_DataSource in
+ *  \li Seamless use of OpenCascade in gmio(see \ref gmio_support module)
- *      gmio(see \c gmioSupport module)
  *
  *  In this module, the name of all entities(structures, functions, ...) are
  *  prefixed either with :
@@ -42,6 +40,52 @@
  *  \li <tt>gmio_stla</tt>, this applies only for STL ascii
  *  \li <tt>gmio_stlb</tt>, this applies only for STL binary(little/big endian)
  *
+ *  <table>
+ *    <tr>
+ *      <th></th>  <th>Functions</th>  <th>Structures</th>
+ *    </tr>
+ *    <tr>
+ *      <td>Read</td>
+ *      <td>gmio_stl_read()<br/>
+ *          gmio_stl_read_file()<br/>
+ *          gmio_stla_read()<br/>
+ *          gmio_stlb_read()</td>
+ *      <td>gmio_stl_read_options<br/>
+ *          gmio_stl_mesh_creator<br/>
+ *          gmio_stl_mesh_creator_infos<br/>
+ *          gmio_stlb_header</td>
+ *    </tr>
+ *    <tr>
+ *      <td>Write</td>
+ *      <td>gmio_stl_write()<br/>
+ *          gmio_stl_write_file()<br/>
+ *          gmio_stlb_header_write()</td>
+ *      <td>gmio_stl_write_options<br/>
+ *          gmio_stl_mesh<br/>
+ *          gmio_stlb_header</td>
+ *    </tr>
+ *    <tr>
+ *      <td>Infos on contents</td>
+ *      <td>gmio_stl_infos_get()<br/>
+ *          gmio_stla_infos_get_streamsize()</td>
+ *      <td>gmio_stl_infos<br/>
+ *          gmio_stl_infos_get_options</td>
+ *    </tr>
+ *    <tr>
+ *      <td>Detect format</td>
+ *      <td>gmio_stl_format_probe()<br/>
+ *          gmio_stl_format_probe_file()</td>
+ *       <td></td>
+ *    </tr>
+ *    <tr>
+ *      <td>Utilities</td>
+ *      <td>gmio_stl_triangle_compute_normal()<br/>
+ *          gmio_stlb_header_str()<br/>
+ *          gmio_stlb_header_to_printable_str()</td>
+ *      <td>gmio_stl_triangle</td>
+ *    </tr>
+ *  </table>
+ *
  *  \addtogroup gmio_stl
  *  @{
  */

src/gmio_stl/stl_infos.h

@@ -93,7 +93,7 @@ enum gmio_stl_info_flag
 /*! Options of function gmio_stl_infos_get() */
 struct gmio_stl_infos_get_options
 {
-    /*! See gmio_core_readwrite_options::stream_memblock */
+    /*! See gmio_stl_read_options::stream_memblock */
     struct gmio_memblock stream_memblock;
 
     /*! Assume STL input format, if GMIO_STL_FORMAT_UNKNOWN then it is

src/gmio_stl/stl_io.h

@@ -35,6 +35,10 @@
 GMIO_C_LINKAGE_BEGIN
 
 /*! Reads STL mesh from stream, format is automatically guessed
+ *
+ *  The user mesh is created sequentially by calling
+ *  gmio_stl_mesh_creator::func_add_triangle() with each triangle read from
+ *  the stream.
  *
  *  It does nothing on the triangles read : no checking(eg. for Nan values),
  *  normals are given as they are.

src/gmio_support/stl_occ_meshvs.h

@@ -61,7 +61,7 @@ gmio_stl_mesh gmio_stl_occmesh(const gmio_stl_occmesh_datasource_iterator& it);
 struct gmio_stl_occmesh_datasource_iterator
 {
     gmio_stl_occmesh_datasource_iterator();
-    explicit gmio_stl_occmesh_datasource_iterator(const MeshVS_DataSource* data_src);
+    explicit gmio_stl_occmesh_datasource_iterator(const MeshVS_DataSource* ds);
     explicit gmio_stl_occmesh_datasource_iterator(const Handle_MeshVS_DataSource& hnd);
 
     inline const MeshVS_DataSource* data_src() const { return m_data_src; }

src/gmio_support/support_global.h

@@ -22,14 +22,55 @@
  *  \c gmioSupport is the bridge between \c gmio and other 3rd-party libraries
  *  (eg. OpenCascade, Qt, ...)\n
  *
- *                           STL
+ *  <table> <caption>OpenCascade support</caption>
- *                     import | export
+ *    <tr>  <th></th> <th colspan="3">STL</th>  </tr>
- *  StlMesh_Mesh       yes      yes
+ *    <tr>  <td></td> <th>import</th> <th>export</th> <th>header</th>  </tr>
- *  MeshVS_DataSource  no       yes
+ *    <tr>
- *  TopoDS_Shape       no       yes
+ *      <td>StlMesh_Mesh</td>
+ *      <td style="color:green">yes</td>
+ *      <td style="color:green">yes</td>
+ *      <td>stl_occ_mesh.h</td>
+ *    </tr>
+ *    <tr>
+ *      <td>MeshVS_DataSource</td>
+ *      <td style="color:red">no</td>
+ *      <td style="color:green">yes</td>
+ *      <td>stl_occ_meshvs.h</td>
+ *    </tr>
+ *    <tr>
+ *      <td>TopoDS_Shape</td>
+ *      <td style="color:red">no</td>
+ *      <td style="color:green">yes</td>
+ *      <td>stl_occ_brep.h</td>
+ *    </tr>
+ *  </table>
  *
- *  Nonetheless, to avoid the \c gmio library being dependent of some other
+ *  \n
- *  binaries, compilation of \c gmioSupport is left to the developer.\n
+ *
+ *  <table> <caption>I/O stream support</caption>
+ *    <tr>  <th></th> <th>read</th> <th>write</th> <th>header</th>  </tr>
+ *    <tr>
+ *      <td>Qt QIODevice</td>
+ *      <td style="color:green">yes</td>
+ *      <td style="color:green">yes</td>
+ *      <td>stream_qt.h</td>
+ *    </tr>
+ *    <tr>
+ *      <td>std::basic_istream<></td>
+ *      <td style="color:green">yes</td>
+ *      <td style="color:red">no</td>
+ *      <td>stream_cpp.h</td>
+ *    </tr>
+ *    <tr>
+ *      <td>std::basic_ostream<></td>
+ *      <td style="color:red">no</td>
+ *      <td style="color:green">yes</td>
+ *      <td>stream_cpp.h</td>
+ *    </tr>
+ *  </table>
+ *
+ *  To avoid the dependency of \c gmio library on some other binaries,
+ *  compilation of \c gmioSupport is left to the developer.\n
  *  For example if Qt streams are needed then the target project must build
  *  somehow <tt>gmio_support/stream_qt.cpp</tt>\n
  *  All \c gmio_support source files are copied with install target (ie by doing
@@ -39,6 +80,24 @@
  *  @{
  */
 
+/*
+ *  OpenCascade support :
+ *   |                   |       STL       |
+ *   |                   | import | export |
+ *   |-------------------|--------|--------|
+ *   | StlMesh_Mesh      |  yes   |  yes   |
+ *   | MeshVS_DataSource |  no    |  yes   |
+ *   | TopoDS_Shape      |  no    |  yes   |
+ *
+ *  I/O stream support :
+ *   |                      | read | write |
+ *   |----------------------|------|-------|
+ *   | Qt QIODevice         |  yes |  yes  |
+ *   | std::basic_istream<> |  yes |  no   |
+ *   | std::basic_ostream<> |  no  |  yes  |
+ *
+ */
+
 #ifndef GMIO_SUPPORT_GLOBAL_H
 #define GMIO_SUPPORT_GLOBAL_H