Improve generated documentation

doc/Doxyfile

@@ -307,7 +307,7 @@ INLINE_GROUPED_CLASSES = NO
 # structs, classes, and unions are shown on a separate page (for HTML and Man 
 # pages) or section (for LaTeX and RTF).
 
-INLINE_SIMPLE_STRUCTS  = NO
+INLINE_SIMPLE_STRUCTS  = YES
 
 # When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum 
 # is documented as struct, union, or enum with the name of the typedef. So 
@@ -673,7 +673,7 @@ INPUT_ENCODING         = UTF-8
 # *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py 
 # *.f90 *.f *.for *.vhd *.vhdl
 
-FILE_PATTERNS          = 
+FILE_PATTERNS          = *.h
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories 
 # should be searched for input files as well. Possible values are YES and NO. 
@@ -1130,7 +1130,7 @@ GENERATE_TREEVIEW      = NO
 # documentation. Note that a value of 0 will completely suppress the enum 
 # values from appearing in the overview section.
 
-ENUM_VALUES_PER_LINE   = 4
+ENUM_VALUES_PER_LINE   = 0
 
 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be 
 # used to set the initial width (in pixels) of the frame in which the tree 

doc/main_page.cpp

@@ -14,29 +14,8 @@ GeomIO is a fast and portable C library for reading and writing geometry data.
 
 \section build_sec BUILDING GeomIO library
 
-The GeomIO library can be built with qmake or cmake.
+The GeomIO library can be built with cmake.
-
+Once makefiles are generated, init tests can be run with "make check"
-<b>With qmake :</b>
-\code
-  .../gmio$ cd qmake
-  .../gmio$ qmake PREFIX_DIR=../gcc-linux64
-  .../gmio$ make all
-  .../gmio$ make install
-\endcode
-
-If you want static libraries (instead of DLLs) just add "CONFIG+=staticlib" to the qmake command :
-\code
-  .../gmio$ qmake PREFIX_DIR=../gcc-linux64 CONFIG+=staticlib
-\endcode
-
-Note that on Windows, qmake complains about deprecated support of backslash '\' characters.
-So you may have to escape backslashes like C:\\path\\to\\opencascade or simply use Unix separators
-instead C:/path/to/opencascade
-
-
-<b>With CMake :</b>
-<TO_BE_DONE>
-
 
 \section reportbug_sec HOW TO REPORT A BUG
 

src/gmio_core/stream.c

@@ -4,57 +4,6 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-/*! \struct gmio_stream
- *
- *  \details This is pretty much the same as [custom streams]
- *  (http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams) in the GNU C Library
- *
- * It uses a cookie being basically an opaque pointer on a hidden data type.\n The custom stream is
- * implemented by defining hook functions that know how to read/write the data.
- */
-
-/*! \var gmio_bool_t (*gmio_stream::at_end_func)(void*)
- *
- *  Checks whether the end-of-stream indicator associated with stream pointed by \p cookie is set,
- *  returning GMIO_TRUE if is.
- *
- *  The function should behaves like C standard [feof()]
- *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/feof.html)
- */
-
-/*! \var int (*gmio_stream::error_func)(void*)
- *
- *  Checks if the error indicator associated with stream pointed by \p cookie is set, returning
- *  a value different from zero if it is.
- *
- *  The function should behaves like C standard [ferror()]
- *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/ferror.html)
- */
-
-/*! \var size_t (*gmio_stream::read_func)(void*, void*, size_t, size_t)
- *
- *  Reads an array of \p count elements, each one with a size of \p size bytes, from the stream
- *  pointed by \p cookie and stores them in the block of memory specified by \p ptr
- *
- *  The function should behaves like C standard [fread()]
- *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/fread.html)
- *
- *  \returns The total number of elements successfully read
- */
-
-/*! \var size_t (*gmio_stream::write_func)(void*, const void*, size_t, size_t);
- *
- *  Writes an array of \p count elements, each one with a size of \p size bytes, from the
- *  block of memory pointed by \p ptr to the current position in the stream pointed by \p cookie
- *
- *  The function should behaves like C standard [fwrite()]
- * (http://pubs.opengroup.org/onlinepubs/007904975/functions/fwrite.html)
- *
- *  \returns The total number of elements successfully written
- */
-
-
-
 void gmio_stream_set_null(gmio_stream_t* stream)
 {
   memset(stream, 0, sizeof(gmio_stream_t));
@@ -95,11 +44,6 @@ void gmio_stream_set_stdio(gmio_stream_t* stream, FILE* file)
   stream->write_func = gmio_stream_stdio_write;
 }
 
-/*! \details Basically the same as :
- *  \code
- *    stream->at_end_func(stream->cookie)
- *  \endcode
- */
 gmio_bool_t gmio_stream_at_end(gmio_stream_t* stream)
 {
   if (stream != NULL && stream->at_end_func != NULL)
@@ -107,11 +51,6 @@ gmio_bool_t gmio_stream_at_end(gmio_stream_t* stream)
   return 0;
 }
 
-/*! \details Basically the same as :
- *  \code
- *    stream->error_func(stream->cookie)
- *  \endcode
- */
 int gmio_stream_error(gmio_stream_t* stream)
 {
   if (stream != NULL && stream->error_func != NULL)
@@ -119,11 +58,6 @@ int gmio_stream_error(gmio_stream_t* stream)
   return 0;
 }
 
-/*! \details Basically the same as :
- *  \code
- *    stream->read_func(stream->cookie)
- *  \endcode
- */
 size_t gmio_stream_read(gmio_stream_t* stream, void *ptr, size_t size, size_t count)
 {
   if (stream != NULL && stream->read_func != NULL)
@@ -131,11 +65,6 @@ size_t gmio_stream_read(gmio_stream_t* stream, void *ptr, size_t size, size_t co
   return 0;
 }
 
-/*! \details Basically the same as :
- *  \code
- *    stream->write_func(stream->cookie)
- *  \endcode
- */
 size_t gmio_stream_write(gmio_stream_t* stream, const void *ptr, size_t size, size_t count)
 {
   if (stream != NULL && stream->write_func != NULL)

src/gmio_core/stream.h

@@ -6,52 +6,108 @@
 
 GMIO_C_LINKAGE_BEGIN
 
-/*! Stream that can get input from an arbitrary data source or can write output to an arbitrary
+/*! \brief Stream that can get input from an arbitrary data source or can write
- *  data sink. It can be seen as generalization of the standard FILE*
+ *         output to an arbitrary data sink.
+ *
+ *  It can be seen as generalization of the standard \c FILE*, and is pretty
+ *  much the same as [custom streams]
+ *  (http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams)
+ *  in the GNU C Library
+ *
+ *  It uses a cookie being basically an opaque pointer on a hidden data type.\n
+ *  The custom stream is implemented by defining hook functions that know how
+ *  to read/write the data.
  */
 struct gmio_stream
 {
-  /*! Opaque pointer on the user stream, passed as first argument to hook functions */
+  /*! \brief Opaque pointer on the user stream, passed as first argument to
+   *         hook functions */
   void* cookie;
 
-  /*! Pointer on a function that checks end-of-stream indicator */
+  /*! \brief Pointer on a function that checks end-of-stream indicator
+   *
+   *  Checks whether the end-of-stream indicator associated with stream
+   *  pointed by \p cookie is set, returning GMIO_TRUE if is.
+   *
+   *  The function should behaves like C standard [feof()]
+   *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/feof.html)
+   */
   gmio_bool_t (*at_end_func)(void* cookie);
 
-  /*! Pointer on a function that checks error indicator */
+  /*! \brief Pointer on a function that checks error indicator
-  int         (*error_func)(void* cookie);
+   *
+   *  Checks if the error indicator associated with stream pointed by \p cookie
+   *  is set, returning a value different from zero if it is.
+   *
+   *  The function should behaves like C standard [ferror()]
+   *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/ferror.html)
+   */
+  int (*error_func)(void* cookie);
 
-  /*! Pointer on a function that reads block of data from stream */
+  /*! \brief Pointer on a function that reads block of data from stream
-  size_t      (*read_func)(void* cookie, void* ptr, size_t size, size_t count);
+   *
+   *  \details Reads an array of \p count elements, each one with a size of \p size
+   *  bytes, from the stream pointed by \p cookie and stores them in the block
+   *  of memory specified by \p ptr
+   *
+   *  The function should behaves like C standard [fread()]
+   *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/fread.html)
+   *
+   *  \returns The total number of elements successfully read
+   */
+  size_t (*read_func)(void* cookie, void* ptr, size_t size, size_t count);
 
-  /*! Pointer on a function that writes block of data to stream */
+  /*! \brief Pointer on a function that writes block of data to stream
-  size_t      (*write_func)(void* cookie, const void* ptr, size_t size, size_t count);
+   *
+   *  \details Writes an array of \p count elements, each one with a size of \p size
+   *  bytes, from the block of memory pointed by \p ptr to the current position
+   *  in the stream pointed by \p cookie
+   *
+   *  The function should behaves like C standard [fwrite()]
+   *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/fwrite.html)
+   *
+   *  \returns The total number of elements successfully written
+   */
+  size_t (*write_func)(void* cookie, const void* ptr, size_t size, size_t count);
 };
 
 typedef struct gmio_stream gmio_stream_t;
 
 /* Initialization */
 
-/*! Installs a null stream */
+/*! \brief Installs a null stream */
 GMIO_LIB_EXPORT void gmio_stream_set_null(gmio_stream_t* stream);
 
-/*! Configures \p stream for standard FILE* (cookie will hold \p file) */
+/*! \brief Configures \p stream for standard FILE* (cookie will hold \p file) */
 GMIO_LIB_EXPORT void gmio_stream_set_stdio(gmio_stream_t* stream, FILE* file);
 
 /* Services */
 
-/*! Safe and convenient function for gmio_stream::at_end_func() */
+/*! \brief Safe and convenient function for gmio_stream::at_end_func()
+ *
+ *  Same as: \code stream->at_end_func(stream->cookie) \endcode
+ */
 GMIO_LIB_EXPORT gmio_bool_t gmio_stream_at_end(gmio_stream_t* stream);
 
-/*! Safe and convenient function for gmio_stream::error_func() */
+/*! \brief Safe and convenient function for gmio_stream::error_func()
+ *
+ *  Same as: \code stream->error_func(stream->cookie) \endcode
+ */
 GMIO_LIB_EXPORT int gmio_stream_error(gmio_stream_t* stream);
 
-/*! Safe and convenient function for gmio_stream::read_func() */
+/*! \brief Safe and convenient function for gmio_stream::read_func()
+ *
+ *  Same as: \code stream->read_func(stream->cookie) \endcode
+ */
 GMIO_LIB_EXPORT size_t gmio_stream_read(gmio_stream_t* stream,
                                         void* ptr,
                                         size_t size,
                                         size_t count);
 
-/*! Safe and convenient function for gmio_stream::write_func() */
+/*! \brief Safe and convenient function for gmio_stream::write_func()
+ *
+ *  Same as: \code stream->write_func(stream->cookie) \endcode
+ */
 GMIO_LIB_EXPORT size_t gmio_stream_write(gmio_stream_t* stream,
                                          const void* ptr,
                                          size_t size,

src/gmio_core/transfer.h

@@ -11,7 +11,7 @@ struct gmio_transfer
   /*! The stream object to be used for I/O */
   gmio_stream_t       stream;
 
-  /*! The optional control object used to handle progress of the transfer */
+  /*! The optional object used to control execution of the transfer */
   gmio_task_control_t task_control;
 
   /*! Pointer on a memory buffer used by the transfer for stream operations */

src/gmio_stl/stl_format.c

@@ -11,16 +11,6 @@
 
 #define _INTERNAL_GMIO_FIXED_BUFFER_SIZE  512
 
-/*! \brief Returns the format of the STL data in \p stream
- *
- *  It will try to read 512 bytes from \p stream into a buffer and then analyses this data to guess
- *  the format.
- *
- *  Parameter \p data_size must provide the total size (in bytes) of the stream data (e.g. file
- *  size), it is required to guess endianness in case of binary format.
- *
- *  Returns GMIO_STL_UNKNOWN_FORMAT in case of error.
- */
 gmio_stl_format_t gmio_stl_get_format(gmio_stream_t *stream, size_t data_size)
 {
   char fixed_buffer[_INTERNAL_GMIO_FIXED_BUFFER_SIZE];

src/gmio_stl/stl_format.h

@@ -17,6 +17,16 @@ enum gmio_stl_format
 
 typedef enum gmio_stl_format gmio_stl_format_t;
 
+/*! \brief Returns the format of the STL data in \p stream
+ *
+ *  It will try to read 512 bytes from \p stream into a buffer and then analyses this data to guess
+ *  the format.
+ *
+ *  Parameter \p data_size must provide the total size (in bytes) of the stream data (e.g. file
+ *  size), it is required to guess endianness in case of binary format.
+ *
+ *  Returns GMIO_STL_UNKNOWN_FORMAT in case of error.
+ */
 GMIO_LIBSTL_EXPORT
 gmio_stl_format_t gmio_stl_get_format(gmio_stream_t* stream, size_t data_size);
 

src/gmio_stl/stl_mesh_creator.h

@@ -4,29 +4,35 @@
 #include "stl_global.h"
 #include "stl_triangle.h"
 
-/*! Provides an interface for the creation of the underlying(hidden) user mesh */
+/*! \brief Provides an interface for the creation of the underlying(hidden)
+ *         user mesh
+ */
 struct gmio_stl_mesh_creator
 {
-  /*! Opaque pointer on the user mesh, passed as first argument to hook functions */
+  /*! \brief Opaque pointer on the user mesh, passed as first argument to hook
+   *         functions
+   */
   void* cookie;
 
   /* All function pointers are optional (ie can be set to NULL) */
 
-  /*! Pointer on a function that handles declaration of a solid of name \p solid_name .
+  /*! \brief 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. gmio_stla_read())
+   *  Optional function useful only with STL ascii (ie. gmio_stla_read())
    */
   void (*ascii_begin_solid_func)(void* cookie, const char* solid_name);
 
-  /*! Pointer on a function that handles declaration of a mesh with \p tri_count number of triangles.
+  /*! \brief 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. gmio_stlb_read()).
+   *  Optional function useful only with STL binary (ie. gmio_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.
+  /*! \brief Pointer on a function that adds a triangle to the user mesh
    *
    *  The argument \p triangle is the triangle to be added, note that
    *  gmio_stl_triangle_t::attribute_byte_count is meaningless for STL ascii.
@@ -35,10 +41,10 @@ struct gmio_stl_mesh_creator
    */
   void (*add_triangle_func)(void* cookie, uint32_t tri_id, const gmio_stl_triangle_t* triangle);
 
-  /*! Pointer on a function that finalizes creation of the user mesh.
+  /*! \brief 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
+   *  Optional function called at the end of the read process, ie. after all
-   *  been added
+   *  triangles have been added
    */
   void (*end_solid_func)(void* cookie);
 };

src/gmio_stl/stl_triangle.h

@@ -3,7 +3,9 @@
 
 #include "stl_global.h"
 
-/*! Cartesian coordinate entity in 3D space, specifically tailored for STL needs (single-float) */
+/*! \brief Cartesian coordinate entity in 3D space, specifically tailored for
+ *         STL needs (single-float)
+ */
 struct gmio_stl_coords
 {
   gmio_real32_t x;
@@ -13,14 +15,16 @@ struct gmio_stl_coords
 
 typedef struct gmio_stl_coords gmio_stl_coords_t;
 
-/*! STL mesh triangle defined three geometric vertices and an orientation(normal) */
+/*! \brief STL mesh triangle defined three geometric vertices and an
+ *         orientation(normal)
+ */
 struct gmio_stl_triangle
 {
   gmio_stl_coords_t normal;
   gmio_stl_coords_t v1;
   gmio_stl_coords_t v2;
   gmio_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 gmio_stl_triangle gmio_stl_triangle_t;

src/gmio_support/occ_libstl.h

@@ -6,6 +6,10 @@
 struct gmio_stl_mesh;
 struct gmio_stl_mesh_creator;
 
+/*! \brief Domain in a StlMesh_Mesh object
+ *
+ *  The domain is indicated with its index within the STL mesh
+ */
 class GMIO_LIBSUPPORT_EXPORT gmio_OccStlMeshDomain
 {
 public:
@@ -22,9 +26,17 @@ private:
   int m_domainId;
 };
 
+/*! \brief Initializes \p mesh so it maps to a domain in StlMesh_Mesh
+ *
+ *  \c mesh->cookie will point to \p meshCookie
+ */
 GMIO_LIBSUPPORT_EXPORT
 void gmio_stl_occmesh(gmio_stl_mesh* mesh, const gmio_OccStlMeshDomain& meshCookie);
 
+/*! \brief Initializes \p creator to build a new domain in a StlMesh_Mesh object
+ *
+ *  \c creator->cookie will point to the internal data(ie. StlMesh_Mesh*) of handle \p mesh
+ */
 GMIO_LIBSUPPORT_EXPORT
 void gmio_stl_occmesh_creator(gmio_stl_mesh_creator* creator, const Handle_StlMesh_Mesh& mesh);
 

src/gmio_support/qt_stream.h

@@ -5,6 +5,8 @@
 struct gmio_stream;
 class QIODevice;
 
+/*! \brief Configures \p stream for \c QIODevice* (cookie will hold \p device)
+ */
 GMIO_LIBSUPPORT_EXPORT
 void gmio_stream_set_qiodevice(struct gmio_stream* stream, QIODevice* device);