Minor fixes/improvements on the doxygen doc

src/gmio_amf/amf_document.h

@@ -377,3 +377,4 @@ struct gmio_amf_document
 };
 
 #endif /* GMIO_AMF_DOCUMENT_H */
+/*! @} */

src/gmio_amf/amf_error.h

@@ -41,8 +41,7 @@
  *  Byte-mask to tag(identify) AMF-specific error codes */
 enum { GMIO_AMF_ERROR_TAG = 0x12000000 };
 
-/*! This enum defines the specific error codes reported by AMF read/write
+/*! Specific error codes reported by AMF read/write functions */
- *  functions */
 enum gmio_amf_error
 {
     /*! The input gmio_amf_document is \c NULL */

src/gmio_amf/amf_io_options.h

@@ -85,3 +85,4 @@ struct gmio_amf_write_options
 };
 
 #endif /* GMIO_AMF_IO_OPTIONS_H */
+/*! @} */

src/gmio_core/const_string.h

@@ -85,3 +85,4 @@ bool gmio_const_string_is_empty(const struct gmio_const_string* str)
 }
 
 #endif /* GMIO_CONST_STRING_H */
+/*! @} */

src/gmio_core/endian.h

@@ -39,7 +39,7 @@
 
 #include "global.h"
 
-/*! This enum identifies common endianness (byte order) of computer memory */
+/*! Common endianness (byte order) of computer memory */
 enum gmio_endianness
 {
     /*! Other (unknown) byte-order */
@@ -56,12 +56,11 @@ enum gmio_endianness
 #ifdef GMIO_HOST_IS_BIG_ENDIAN
     GMIO_ENDIANNESS_HOST = GMIO_ENDIANNESS_BIG
 #else
-    /*! Defines the endianness(byte order) used by the host computer for
+    /*! Endianness(byte order) used by the host computer for storing data in
-     *  storing data in memory.
+     *  memory.
      *
-     *  It is set at configure-time to either GMIO_ENDIANNESS_LITTLE or
+     *  Set at configure-time to either GMIO_ENDIANNESS_LITTLE or
-     *  GMIO_ENDIANNESS_BIG
+     *  GMIO_ENDIANNESS_BIG */
-     */
     GMIO_ENDIANNESS_HOST = GMIO_ENDIANNESS_LITTLE
 #endif
 };

src/gmio_core/error.h

@@ -43,7 +43,7 @@
  *  Byte-mask to tag(identify) zlib-specific error codes */
 enum { GMIO_ZLIB_ERROR_TAG = 0x1000000 };
 
-/*! This enum defines common errors */
+/*! Common errors */
 enum gmio_error
 {
     /*! No error occurred, success */
@@ -52,7 +52,7 @@ enum gmio_error
     /*! Unknown error */
     GMIO_ERROR_UNKNOWN,
 
-    /*! Pointer on argument memory block is NULL */
+    /*! Pointer on argument memory block is \c NULL */
     GMIO_ERROR_NULL_MEMBLOCK,
 
     /*! Argument size for the memory block is too small */
@@ -65,10 +65,8 @@ enum gmio_error
      *  gmio_task_iface::func_is_stop_requested() returned true */
     GMIO_ERROR_TASK_STOPPED,
 
-    /*! An error occured after a call to a <stdio.h> function
+    /*! An error occured after a call to a \c <stdio.h> function.
-     *
+     *  The caller can check \c errno to get the real error number */
-     *  The caller can check errno to get the real error number
-     */
     GMIO_ERROR_STDIO,
 
     /*! Checking of \c LC_NUMERIC failed(should be "C" or "POSIX") */

src/gmio_core/internal/byte_swap.h

@@ -58,8 +58,7 @@ GMIO_INLINE uint32_t gmio_uint32_bswap(uint32_t val)
 #elif defined(GMIO_HAVE_MSVC_BUILTIN_BSWAP_FUNC)
     return _byteswap_ulong(val);
 #else
-    return
+    return ((val & 0x000000FF) << 24)
-            ((val & 0x000000FF) << 24)
             | ((val & 0x0000FF00) << 8)
             | ((val >> 8) & 0x0000FF00)
             | ((val >> 24) & 0x000000FF);

src/gmio_core/internal/ostringstream.h

@@ -37,7 +37,7 @@
 
 /*! Output stream that operates on a string
  *
- *  To be used with API below.
+ *  To be used with API below
  */
 struct gmio_ostringstream
 {
@@ -56,7 +56,7 @@ struct gmio_ostringstream
             void* cookie, struct gmio_stream* stream, const char* ptr, size_t len);
 };
 
-/*! Returns an initialized gmio_ostringstream object */
+/*! Returns an initialized ostringstream */
 struct gmio_ostringstream gmio_ostringstream(
         const struct gmio_stream stream,
         const struct gmio_string strbuff);
@@ -124,13 +124,13 @@ GMIO_INLINE void gmio_ostringstream_flush(struct gmio_ostringstream* sstream);
 
 /* XML */
 
-/*! Write XML attribute of name \p attr and value \p val */
+/*! Writes XML attribute of name \p attr and value \p val */
 void gmio_ostringstream_write_xmlattr_str(
         struct gmio_ostringstream* sstream, const char* attr, const char* val);
 void gmio_ostringstream_write_xmlattr_u32(
         struct gmio_ostringstream* sstream, const char* attr, uint32_t val);
 
-/*! Write XML element containing \p val : <elt>val</elt> */
+/*! Writes XML element containing \p val : <elt>val</elt> */
 void gmio_ostringstream_write_xmlelt_f64(
         struct gmio_ostringstream* sstream, const char* elt, double val);
 

src/gmio_core/internal/string.h

@@ -46,16 +46,12 @@ struct gmio_string
     size_t capacity; /*!< Maximum contents size */
 };
 
-/*! Returns an initialized struct gmio_string object
+/*! Returns an initialized struct string.
- *
+ *  gmio_string::capacity is set to <tt>max(len,capacity)</tt> */
- *  gmio_string::capacity is set to <tt>max(len,capacity)</tt>
- */
 GMIO_INLINE struct gmio_string gmio_string(char* ptr, size_t len, size_t capacity);
 
-/*! Clears the contents of the string \p str and makes it null
+/*! Clears the contents of the string \p str and makes it null.
- *
+ *  \warning Memory pointed to by gmio_string::ptr is not freed in any way */
- *  \warning Memory pointed to by gmio_string::ptr is not freed in any way
- */
 GMIO_INLINE void gmio_string_clear(struct gmio_string* str);
 
 /*! Returns a pointer after the last character of \p str */

src/gmio_core/internal/string_ascii_utils.h

@@ -52,37 +52,27 @@ GMIO_INLINE char gmio_ascii_toupper(char c);
 /*! Returns the uppercase letter converted to lowercase */
 GMIO_INLINE char gmio_ascii_tolower(char c);
 
-/*! Returns 0 if \p c1 compare equals to \p c2, non-zero otherwise
+/*! Returns 0 if \p c1 compare equals to \p c2, non-zero otherwise.
- *
+ *  \note Comparison is case-insensitive */
- *  Comparison is case-insensitive
- */
 GMIO_INLINE bool gmio_ascii_char_iequals(char c1, char c2);
 
-/*! Returns 0 if \p str1 and \p str2 compare equal, non-zero otherwise
+/*! Returns 0 if \p str1 and \p str2 compare equal, non-zero otherwise.
- *
+ *  \note Comparison is case-insensitive */
- *  Comparison is case-insensitive
- */
 GMIO_INLINE int gmio_ascii_stricmp(const char* str1, const char* str2);
 
-/*! Returns 0 if the first \p n characreters of \p str1 and \p str2 compare
+/*! Returns 0 if the first \p n characters of \p str1 and \p str2 compare equal,
- *  equal, non-zero otherwise
+ *  non-zero otherwise.
- *
+ *  \note Comparison is case-insensitive */
- *  Comparison is case-insensitive
- */
 GMIO_INLINE int gmio_ascii_strincmp(
         const char* str1, const char* str2, size_t n);
 
-/*! Returns true if \p str starts with string \p begin
+/*! Returns true if \p str starts with string \p begin.
- *
+ *  \note Comparison is case-insensitive */
- *  Comparison is case-insensitive
- */
 GMIO_INLINE bool gmio_ascii_istarts_with(
         const char* str, const char* begin);
 
-/*! Locate substring (insensitive case string matching)
+/*! Locate substring (insensitive case string matching).
- *
+ *  Behaves the same as strstr() */
- *  Behaves the same as strstr()
- */
 const char* gmio_ascii_istrstr(const char *str1, const char *str2);
 
 

src/gmio_core/internal/stringstream.h

@@ -58,13 +58,12 @@ struct gmio_stringstream
     /*! Data to be passed to callback func_stream_read */
     void* cookie;
 
-    /*! Pointer on a function called each time next contents chunk has to be
+    /*! Pointer on a function called each time next contents chunk has to be read */
-     * read */
     size_t (*func_stream_read)(
             void* cookie, struct gmio_stream* stream, char* ptr, size_t len);
 };
 
-/*! Returns an initialized gmio_stringstream object */
+/*! Returns an initialized stringstream */
 struct gmio_stringstream gmio_stringstream(
         const struct gmio_stream stream,
         const struct gmio_string strbuff);
@@ -110,10 +109,8 @@ enum gmio_eat_word_error gmio_stringstream_eat_word(
         struct gmio_stringstream* sstream, struct gmio_string* str);
 
 #if 0
-/*! Iterate over stream while it matches input string \p str
+/*! Iterate over stream while it matches input string \p str.
- *
+ *  Returns true if \p str was fully matched */
- *  Returns true if \p str was fully matched
- */
 bool gmio_stringstream_checked_next_chars(
         struct gmio_stringstream* sstream, const char* str);
 #endif

src/gmio_core/internal/zlib_utils.h

@@ -34,35 +34,35 @@
 #include "../zlib_compress.h"
 #include <zlib.h>
 
-/* Converts zlib error to gmio "zlib-specific" error */
+/*! Converts zlib error to gmio "zlib-specific" error */
 int zlib_error_to_gmio_error(int z_error);
 
-/* Wrapper around deflateInit2(), returns a converted gmio error code */
+/*! Wrapper around deflateInit2(), returns a converted gmio error code */
 int gmio_zlib_compress_init(
         struct z_stream_s* z_stream,
         const struct gmio_zlib_compress_options* z_opts);
 
-/* Checks zlib compression options */
+/*! Checks zlib compression options */
 bool gmio_check_zlib_compress_options(
         int* error, const struct gmio_zlib_compress_options* z_opts);
 
-/* Decompresses the source buffer into the destination buffer.
+/*! Decompresses the source buffer into the destination buffer.
  *
- * \p sourceLen is the byte length of the source buffer. Upon entry, \p destLen
+ *  \p sourceLen is the byte length of the source buffer. Upon entry, \p destLen
- * is the total size of the destination buffer, which must be large enough to
+ *  is the total size of the destination buffer, which must be large enough to
- * hold the entire uncompressed data.
+ *  hold the entire uncompressed data.
- * Upon exit, destLen is the actual size of the compressed buffer.
+ *  Upon exit, destLen is the actual size of the compressed buffer.
  */
 int gmio_zlib_uncompress_buffer(
         uint8_t* dest, size_t* dest_len, const uint8_t* src, size_t src_len);
 
-/* Computes the CRC-32 value with the bytes buff[0..buff_len-1] */
+/*! Computes the CRC-32 value with the bytes buff[0..buff_len-1] */
 uint32_t gmio_zlib_crc32(const uint8_t* buff, size_t buff_len);
 
-/* Returns the required initial value for the gmio_zlib_crc32_update() */
+/*! Returns the required initial value for the gmio_zlib_crc32_update() */
 uint32_t gmio_zlib_crc32_initial();
 
-/* Updates a running CRC-32 with the bytes buff[0..buff_len-1] */
+/*! Updates a running CRC-32 with the bytes buff[0..buff_len-1] */
 uint32_t gmio_zlib_crc32_update(
         uint32_t crc, const uint8_t* buff, size_t buff_len);
 

src/gmio_core/memblock.h

@@ -46,7 +46,7 @@
  *  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
+ *  Binding a memblock to some statically-allocated memory is done through
  *  gmio_memblock() :
  *  \code{.c}
  *      char buff[512] = {0};
@@ -54,7 +54,7 @@
  *                  gmio_memblock(buff, GMIO_ARRAY_SIZE(buff), NULL);
  *  \endcode
  *
- *  Any gmio_memblock object can be safely freed with gmio_memblock_deallocate()
+ *  Any memblock can be safely freed with gmio_memblock_deallocate()
  */
 struct gmio_memblock
 {
@@ -77,27 +77,23 @@ GMIO_C_LINKAGE_BEGIN
 /*! Returns true if \p mblock is NULL or points to null/void memory */
 GMIO_API bool gmio_memblock_isnull(const struct gmio_memblock* mblock);
 
-/*! Returns an initialized gmio_memblock object
+/*! Returns an initialized memblock object.
- *
  *  If \p ptr is NULL then gmio_memblock::size is forced to \c 0
  */
 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 memblock 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 memblock 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 memblock 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);
@@ -105,7 +101,7 @@ GMIO_API struct gmio_memblock gmio_memblock_realloc(void* ptr, size_t size);
 /*! Safe and convenient call to gmio_memblock::func_deallocate() */
 GMIO_API void gmio_memblock_deallocate(struct gmio_memblock* mblock);
 
-/*! Typedef for a pointer to a function that creates an allocated mblock
+/*! Typedef for a pointer to a function that creates an allocated memblock
  *
  *  Signature:
  *  \code{.c} struct gmio_memblock mblock_ctor(); \endcode
@@ -114,22 +110,22 @@ 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
+ *  The constructor function allocates a memblock on demand, to be used when a
- *  used when a temporary memblock is needed.
+ *  temporary memblock is needed.
  *
  *  This function is not thread-safe.
  */
 GMIO_API void gmio_memblock_set_default_constructor(
                 gmio_memblock_constructor_func_t ctor);
 
-/*! Returns the currently installed function to construct gmio_memblock objects
+/*! Returns the currently installed function to construct memblock objects.
- *
  *  It is initialized to <tt>gmio_memblock_malloc(128KB)</tt>
  */
 GMIO_API gmio_memblock_constructor_func_t gmio_memblock_default_constructor();
 
-/*! Returns a gmio_memblock object created using the function
+/*! Returns a memblock created with the function
- *  gmio_memblock_default_constructor() */
+ *  gmio_memblock_default_constructor()
+ */
 GMIO_API struct gmio_memblock gmio_memblock_default();
 
 GMIO_C_LINKAGE_END

src/gmio_core/text_format.h

@@ -39,8 +39,7 @@
 
 #include "global.h"
 
-/*! This enum defines the various formats to textually represent a float(single
+/*! Various formats to textually represent a float(single/double precision) */
- *  or double precision) */
 enum gmio_float_text_format
 {
     /*! Decimal floating point, lowercase (ex: 392.65) */

src/gmio_core/zlib_compress.h

@@ -94,3 +94,4 @@ struct gmio_zlib_compress_options
 };
 
 #endif /* GMIO_ZLIB_COMPRESS_H */
+/*! @} */

src/gmio_stl/stl_error.h

@@ -41,8 +41,7 @@
  *  Byte-mask to tag(identify) STL-specific error codes */
 enum { GMIO_STL_ERROR_TAG = 0x11000000 };
 
-/*! This enum defines the various error codes reported by STL read/write
+/*! Specific error codes reported by STL read/write functions */
- *  functions */
 enum gmio_stl_error
 {
     /*! STL format could not be guessed in read function */

src/gmio_stl/stl_format.h

@@ -44,7 +44,7 @@
  *  Byte-mask to tag(identify) STL binary formats */
 enum { GMIO_STL_FORMAT_TAG_BINARY = 0x10 };
 
-/*! This enums defines the various STL formats */
+/*! Various STL formats */
 enum gmio_stl_format
 {
     /*! Unknown STL format */

src/gmio_stl/stl_infos.h

@@ -51,23 +51,18 @@ struct gmio_stl_infos
     /*! Count of facets(triangles) */
     uint32_t facet_count;
 
-    /*! Size of the STL data in bytes
+    /*! Size of the STL data in bytes.
-     *
      *  For STL ascii it includes the "endsolid" tag */
     gmio_streamsize_t size;
 
-    /*! STL ascii only: name of the solid
+    /*! STL ascii only: name of the solid.
-     *
      *  The pointer has to be set before calling gmio_stl_infos_probe()
-     *  \sa stla_solidname_maxlen
+     *  \sa stla_solidname_maxlen */
-     */
     char* stla_solidname;
 
-    /*! STL ascii only: maximum length(capacity) of stla_solidname
+    /*! STL ascii only: maximum length(capacity) of stla_solidname.
-     *
      *  The value has to be set before calling gmio_stl_infos_probe()
-     *  \sa stla_solidname
+     *  \sa stla_solidname */
-     */
     size_t stla_solidname_maxlen;
 
     /*! STL binary only: header(80-bytes) of STL data */
@@ -111,9 +106,7 @@ struct gmio_stl_infos_probe_options
     enum gmio_stl_format format_hint;
 
     /*! Restrict gmio_stl_infos_probe() to not read further this limit(in bytes)
-     *
+     *  \warning Not yet supported */
-     *  \warning Not yet supported
-     */
     gmio_streamsize_t size_limit;
 };