doc: effort to make it complete

README.md

@@ -1,27 +1,50 @@
 GeomIO: C library for geometry input/output
-==============================
+===========================================
 
 This is GeomIO v0.1dev
 
-GeomIO is a reusable ANSI C library whose purpose is to provide complete
+GeomIO is a reusable C library whose purpose is to provide complete I/O
-I/O support for various CAD file formats (eg. STL)
+support for various CAD file formats (eg. STL)
+
+GeomIO aims to be fast, portable (ISO-C90 conformance) and feature-rich.
+Main highlights:
+    * "Abstract" streams that does not tie the user to C stream (`FILE*`).        
+      GeomIO provides a general stream structure based on callbacks, so that
+      any kind of device can be used (memory, file, socket, ...)
+    * Operations can be easily aborted
+    * Buffering of input/ouput for efficient device usage
+    * Available under the CeCILL-B license, which is fully BSD compatible
+
+Current version only supports STL file format (STereoLithgraphy). Support of
+STL is complete:
+    * Binary(little/big endian) and ASCII formats
+    * Header data and "attribute byte count" for binary format
+    * Name of solid for ASCII format
+    * Detection of the input data format
+
+In addition, the STL module has the following advatanges:
+    * The user keeps its own geometry data structures, no conversion needed.
+      This reduces the effort so that the user just specifies callbacks for
+      retrieval/creation of geometry data
+    * No dynamic memory allocations
+    * Extended support of OpenCascade's `StlMesh_Mesh`
 
 
 Building GeomIO
-==================
+===============
 
 GeomIO can be built with CMake, by default a shared library is generated.
     1. For an out-of-source build, create a directory where the build will take
-         place (say build/)
+         place (say `build/`)
-    2. Call cmake, passing as argument the directory where is located
+    2. Call `cmake`, passing as argument the directory where is located
          CMakeLists.txt
-    3. (n)make
+    3. `(n)make`
-    4. (n)make install
+    4. `(n)make install`
 
 Read CMakeLists.txt to figure out how to build debug and release libraries.
 
 For the first use of GeomIO, you should run unit tests:
-    (n)make check
+    `(n)make check`
 
 
 How to report a bug

doc/Doxyfile

@@ -128,7 +128,7 @@ FULL_PATH_NAMES        = YES
 # If left blank the directory from which doxygen is run is used as the 
 # path to strip.
 
-STRIP_FROM_PATH        = /home/cerf/dev/projects/fougue/gmio/src
+STRIP_FROM_PATH        = ../src
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of 
 # the path mentioned in the documentation of a class, which tells 
@@ -657,7 +657,8 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../src
+INPUT                  = ../README.md \
+                         ../src
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -689,7 +690,9 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is 
 # run.
 
-EXCLUDE                = 
+EXCLUDE                = \
+    ../src/gmio_core/memory.h \ # Not used
+    ../src/gmio_support/support_global.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 
@@ -1470,7 +1473,7 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled 
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = YES
+MACRO_EXPANSION        = NO
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
 # then the macro expansion is limited to the macros specified with the 
@@ -1507,9 +1510,8 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = GMIO_LIB_EXPORT= \
                          GMIO_LIBSUPPORT_EXPORT= \
                          GMIO_LIBSTL_EXPORT= \
-                         GMIO_C_LINKAGE_BEGIN= \
+                         GMIO_HAVE_STDINT_H=1 \
-                         GMIO_C_LINKAGE_END= \
+                         DOXYGEN
-                         GMIO_HAVE_STDINT_H=1
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 

src/gmio_core/endian.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file endian.h
+ *  Architecture endianness
+ */
+
 #ifndef GMIO_ENDIAN_H
 #define GMIO_ENDIAN_H
 

src/gmio_core/error.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file error.h
+ *  List of common errors, reported by I/O functions
+ */
+
 #ifndef GMIO_ERROR_H
 #define GMIO_ERROR_H
 

src/gmio_core/global.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file global.h
+ *  Fundamental global declarations, included by almost all other header files
+ */
+
 #ifndef GMIO_GLOBAL_H
 #define GMIO_GLOBAL_H
 
@@ -22,7 +26,9 @@
 #  define GMIO_DECL_EXPORT __declspec(dllexport)
 #  define GMIO_DECL_IMPORT __declspec(dllimport)
 #else
+/*! Expands to the C compiler extension to export functions to a DLL */
 #  define GMIO_DECL_EXPORT
+/*! Expands to the C compiler extension to import functions from a DLL */
 #  define GMIO_DECL_IMPORT
 #endif /* WIN */
 
@@ -33,6 +39,8 @@
 #    define GMIO_LIB_EXPORT GMIO_DECL_IMPORT
 #  endif /* GMIO_LIB_MAKE_DLL */
 #else
+/*! Expands either to GMIO_DECL_EXPORT or GMIO_DECL_IMPORT when respectively
+ *  compiling/using the DLL */
 #  define GMIO_LIB_EXPORT
 #endif /* GMIO_LIB_DLL */
 
@@ -68,23 +76,31 @@ typedef unsigned long long uint64_t;
 #ifdef GMIO_HAVE_STDBOOL_H
 #  include <stdbool.h>
 
-/*! Typedef for boolean type */
 typedef bool gmio_bool_t;
 
 #  define GMIO_FALSE false
 #  define GMIO_TRUE  true
+#elif !defined(DOXYGEN)
+typedef int gmio_bool_t;
 
-#else
-/*! Typedef for boolean type */
-typedef int    gmio_bool_t;
-
-/*! This enum defines true/false boolean values */
 enum gmio_bool_value
 {
     GMIO_FALSE = 0,
     GMIO_TRUE = 1
 };
-
+#else
+/* For documentation only */
+/*! Boolean type alias
+ *
+ *  If strict ISO-C90 or if \c <stdbool.h> does not exists then:
+ *      \li \c gmio_bool_t is an alias of \c int
+ *      \li <tt>GMIO_FALSE == 0</tt> and <tt>GMIO_TRUE == 1</tt>
+ *
+ *  Otherwise:
+ *      \li \c gmio_bool_t is an alias of \c bool
+ *      \li \c GMIO_FALSE expands to \c false and \c GMIO_TRUE to \c true
+ */
+typedef int_or_bool gmio_bool_t;
 #endif /* GMIO_HAVE_STDBOOL_H */
 
 /*! Typedef for 32bit real type (float) */
@@ -102,6 +118,7 @@ typedef double gmio_float64_t;
 #  elif defined(_MSC_VER)
 #    define GMIO_INLINE __inline
 #  else
+/*! Expands to the C compiler specific inline keyword (if any) */
 #    define GMIO_INLINE
 #  endif
 #endif /* !GMIO_INLINE */
@@ -110,7 +127,9 @@ typedef double gmio_float64_t;
 #  define GMIO_C_LINKAGE_BEGIN extern "C" {
 #  define GMIO_C_LINKAGE_END   }
 #else
+/*! Expands to <tt>extern "C" {</tt> when building with a C++ compiler */
 #  define GMIO_C_LINKAGE_BEGIN
+/*! Expands to \c } when building with a C++ compiler */
 #  define GMIO_C_LINKAGE_END
 #endif /* __cplusplus */
 

src/gmio_core/internal/string_parse.h

@@ -19,6 +19,11 @@
 #include "../global.h"
 #include "../stream.h"
 
+/*! Stores traditional 8-bit strings
+ *
+ *  For faster length lookups, it knowns the length of its contents. It must
+ *  never exceeds the maximum length of the buffer.
+ */
 struct gmio_string_buffer
 {
     char*  ptr;     /*!< Buffer contents */
@@ -28,6 +33,12 @@ struct gmio_string_buffer
 
 typedef struct gmio_string_buffer  gmio_string_buffer_t;
 
+/*! Forward iterator over a stream
+ *
+ *  To be used with API below.
+ *  It allows to iterate over a stream (until end is reached) as if it was a
+ *  string.
+ */
 struct gmio_string_stream_fwd_iterator
 {
     gmio_stream_t*       stream;
@@ -45,7 +56,13 @@ const char* gmio_current_char(const gmio_string_stream_fwd_iterator_t* it);
 void  gmio_skip_spaces(gmio_string_stream_fwd_iterator_t* it);
 int   gmio_eat_word(gmio_string_stream_fwd_iterator_t* it, gmio_string_buffer_t* buffer);
 
+/*! Move on next char in stream */
 const char* gmio_next_char(gmio_string_stream_fwd_iterator_t* it);
+
+/*! Iterate over stream while it matches input string \p str
+ *
+ *  Returns GMIO_TRUE if \p str was fully matched
+ */
 gmio_bool_t gmio_checked_next_chars(gmio_string_stream_fwd_iterator_t* it, const char* str);
 
 /*! Converts the string pointed to by \p str to gmio_float32_t representation
@@ -53,6 +70,6 @@ gmio_bool_t gmio_checked_next_chars(gmio_string_stream_fwd_iterator_t* it, const
  *  \retval 0  On success
  *  \retval -1 On error(check \c errno to see what happened)
  */
-int   gmio_get_float32(const char* str, gmio_float32_t* value_ptr);
+int gmio_get_float32(const char* str, gmio_float32_t* value_ptr);
 
 #endif /* GMIO_INTERNAL_STRING_PARSE_H */

src/gmio_core/stream.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stream.h
+ *  Declaration of gmio_stream and utility functions
+ */
+
 #ifndef GMIO_STREAM_H
 #define GMIO_STREAM_H
 

src/gmio_core/task_control.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file task_control.h
+ *  Declaration of gmio_task_control and utility functions
+ */
+
 #ifndef GMIO_TASK_CONTROL_H
 #define GMIO_TASK_CONTROL_H
 

src/gmio_core/transfer.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file transfer.h
+ *  Declaration of gmio_transfer
+ */
+
 #ifndef GMIO_TRANSFER_H
 #define GMIO_TRANSFER_H
 

src/gmio_stl/internal/stl_rw_common.h

@@ -13,6 +13,8 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/* TODO : documentation */
+
 #ifndef GMIO_INTERNAL_STL_RW_COMMON_H
 #define GMIO_INTERNAL_STL_RW_COMMON_H
 

src/gmio_stl/internal/stlb_byte_swap.h

@@ -19,6 +19,11 @@
 #include "../../gmio_core/global.h"
 #include "../stl_triangle.h"
 
+/*! Specific byte-swap of the memory occupied by a gmio_stl_triangle object
+ *
+ *  Each XYZ coord (float32) is individually reversed (byte-swap) as well as
+ *  the "attribute byte count" member.
+ */
 void gmio_stl_triangle_bswap(gmio_stl_triangle_t* triangle);
 
 #endif /* GMIO_INTERNAL_STLB_BYTE_SWAP_H */

src/gmio_stl/stl_error.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stl_error.h
+ *  List of errors specific to STL I/O functions
+ */
+
 #ifndef GMIO_LIBSTL_STL_ERROR_H
 #define GMIO_LIBSTL_STL_ERROR_H
 

src/gmio_stl/stl_format.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stl_format.h
+ *  Detection of STL format from input stream
+ */
+
 #ifndef GMIO_LIBSTL_FORMAT_H
 #define GMIO_LIBSTL_FORMAT_H
 

src/gmio_stl/stl_global.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stl_global.h
+ *  Global declarations for the STL module
+ */
+
 #ifndef GMIO_LIBSTL_GLOBAL_H
 #define GMIO_LIBSTL_GLOBAL_H
 

src/gmio_stl/stl_io.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stl_io.h
+ *  STL read/write functions
+ */
+
 #ifndef GMIO_LIBSTL_STL_IO_H
 #define GMIO_LIBSTL_STL_IO_H
 

src/gmio_stl/stl_mesh.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stl_mesh.h
+ *  Declaration of gmio_stl_mesh
+ */
+
 #ifndef GMIO_LIBSTL_STL_MESH_H
 #define GMIO_LIBSTL_STL_MESH_H
 

src/gmio_stl/stl_mesh_creator.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stl_mesh_creator.h
+ *  Declaration of gmio_stl_mesh_creator
+ */
+
 #ifndef GMIO_LIBSTL_STL_MESH_CREATOR_H
 #define GMIO_LIBSTL_STL_MESH_CREATOR_H
 

src/gmio_stl/stl_triangle.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file stl_triangle.h
+ *  Declaration of gmio_stl_coords and gmio_stl_triangle
+ */
+
 #ifndef GMIO_LIBSTL_TRIANGLE_H
 #define GMIO_LIBSTL_TRIANGLE_H
 

src/gmio_support/occ_libstl.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file occ_libstl.h
+ *  Support of OpenCascade's StlMesh_Mesh
+ */
+
 #ifndef GMIO_SUPPORT_OCC_LIBSTL_H
 #define GMIO_SUPPORT_OCC_LIBSTL_H
 
@@ -21,7 +25,7 @@
 struct gmio_stl_mesh;
 struct gmio_stl_mesh_creator;
 
-/*! \brief Domain in a StlMesh_Mesh object
+/*! Domain in a StlMesh_Mesh object
  *
  *  The domain is indicated with its index within the STL mesh
  */
@@ -41,14 +45,14 @@ private:
   int m_domainId;
 };
 
-/*! \brief Initializes \p mesh so it maps to a domain in StlMesh_Mesh
+/*! 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
+/*! 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
  */

src/gmio_support/qt_stream.h

@@ -13,6 +13,10 @@
 ** "http://www.cecill.info".
 ****************************************************************************/
 
+/*! \file qt_stream.h
+ *  Support of Qt's QIODevice (requires at least Qt4)
+ */
+
 #ifndef GMIO_SUPPORT_QT_STREAM_H
 #define GMIO_SUPPORT_QT_STREAM_H
 
@@ -20,8 +24,7 @@
 struct gmio_stream;
 class QIODevice;
 
-/*! \brief Configures \p stream for \c QIODevice* (cookie will hold \p device)
+/*! 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);