Add more documentation for global header files (just below src/ folder)

doc/Doxyfile

@@ -159,7 +159,7 @@ JAVADOC_AUTOBRIEF      = NO
 # will behave just like regular Qt-style comments (thus requiring 
 # an explicit \brief command for a brief description.)
 
-QT_AUTOBRIEF           = NO
+QT_AUTOBRIEF           = YES
 
 # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen 
 # treat a multi-line C++ special comment block (i.e. a block of //! or /// 
@@ -207,7 +207,7 @@ TCL_SUBST              =
 # For instance, some of the names that are used will be different. The list 
 # of all members will be omitted, etc.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java 
 # sources only. Doxygen will then generate output that is more tailored for 
@@ -447,7 +447,7 @@ HIDE_SCOPE_NAMES       = NO
 # will put a list of the files that are included by a file in the documentation 
 # of that file.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen 
 # will list include files with double quotes in the documentation 
@@ -701,7 +701,7 @@ EXCLUDE_SYMLINKS       = NO
 # against the file with absolute path, so to exclude all test directories 
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = */internal/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names 
 # (namespaces, classes, functions, etc.) that should be excluded from the 
@@ -1468,13 +1468,13 @@ 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        = NO
+MACRO_EXPANSION        = YES
 
 # 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 
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files 
 # pointed to by INCLUDE_PATH will be searched when a #include is found.
@@ -1502,7 +1502,10 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator 
 # instead of the = operator.
 
-PREDEFINED             = 
+PREDEFINED             = FOUG_LIB_EXPORT= \
+                         FOUG_LIBSUPPORT_EXPORT= \
+                         FOUG_DATAX_LIBSTL_EXPORT= \
+                         FOUG_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/endian.c

@@ -10,7 +10,6 @@ typedef union
   uint8_t  bytes[4];
 } _internal_foug_int_bytes_32_convert_t;
 
-/*! Endianness (byte order) of the host's CPU architecture */
 foug_endianness_t foug_host_endianness()
 {
   _internal_foug_int_bytes_32_convert_t conv;

src/endian.h

@@ -3,6 +3,7 @@
 
 #include "global.h"
 
+/*! This enum identifies endian representations of numbers */
 typedef enum
 {
   FOUG_LITTLE_ENDIAN,
@@ -11,6 +12,7 @@ typedef enum
   FOUG_OTHER_ENDIAN
 } foug_endianness_t;
 
+/*! Returns endianness (byte order) of the host's CPU architecture */
 FOUG_LIB_EXPORT foug_endianness_t foug_host_endianness();
 
 #endif /* FOUG_ENDIAN_H */

src/error.h

@@ -3,18 +3,33 @@
 
 #include "global.h"
 
-/* Common errors */
+/*! This enum defines common errors */
 typedef enum
 {
+  /*! No error occurred, success */
   FOUG_DATAX_NO_ERROR = 0,
+
+  /*! Pointer on argument foug_transfer_t is NULL */
   FOUG_DATAX_NULL_TRANSFER_ERROR = -1,
+
+  /*! Pointer on argument buffer is NULL */
   FOUG_DATAX_NULL_BUFFER_ERROR = -2,
+
+  /*! Argument buffer's size is too small */
   FOUG_DATAX_INVALID_BUFFER_SIZE_ERROR = -3,
+
+  /*! An error occurred with the argument foug_stream_t (check foug_stream_error()) */
   FOUG_DATAX_STREAM_ERROR = -4,
+
+  /*! Operation was stopped by user (foug_task_control_t::handle_progress_func() returned false) */
   FOUG_DATAX_TASK_STOPPED_ERROR = -5
+
 } foug_datax_error_t;
 
+/*! Returns true if \p code == FOUG_DATAX_NO_ERROR */
 FOUG_LIB_EXPORT foug_bool_t foug_datax_no_error(int code);
+
+/*! Returns true if \p code != FOUG_DATAX_NO_ERROR */
 FOUG_LIB_EXPORT foug_bool_t foug_datax_error(int code);
 
 #endif /* FOUG_DATAX_C_ERROR_H */

src/global.h

@@ -47,15 +47,20 @@ typedef unsigned long long uint64_t;
 
 #endif /* FOUG_USE_STDINT_H */
 
+/*! Typedef for boolean type */
 typedef int    foug_bool_t;
-typedef float  foug_real32_t;
+/*! This enum defines true/false boolean values */
-typedef double foug_real64_t;
 enum foug_bool_value
 {
   FOUG_FALSE = 0,
   FOUG_TRUE = 1
 };
 
+/*! Typedef for 32bit real type (float) */
+typedef float  foug_real32_t;
+/*! Typedef for 64bit real type (double) */
+typedef double foug_real64_t;
+
 #ifndef FOUG_INLINE
 # if defined(__GNUC__)
 #  define FOUG_INLINE __inline__  /* Compatible with C90 */

src/stream.c

@@ -4,9 +4,6 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-/*!
- * \brief Installs a null stream
- */
 void foug_stream_set_null(foug_stream_t* stream)
 {
   memset(stream, 0, sizeof(foug_stream_t));
@@ -38,9 +35,6 @@ static size_t foug_stream_stdio_write(void* cookie,
   return fwrite(ptr, item_size, item_count, (FILE*) cookie);
 }
 
-/*!
- * \brief Configures \p stream for standard FILE*
- */
 void foug_stream_set_stdio(foug_stream_t* stream, FILE* file)
 {
   stream->cookie = file;
@@ -50,9 +44,6 @@ void foug_stream_set_stdio(foug_stream_t* stream, FILE* file)
   stream->write_func = foug_stream_stdio_write;
 }
 
-/*!
- * \brief Returns true if the current read and write position is at the end of the stream
- */
 foug_bool_t foug_stream_at_end(foug_stream_t* stream)
 {
   if (stream != NULL && stream->at_end_func != NULL)
@@ -60,14 +51,6 @@ foug_bool_t foug_stream_at_end(foug_stream_t* stream)
   return 0;
 }
 
-/*!
- * \brief Checks error indicator
- *
- * Checks if the error indicator associated with \p stream is set, returning a value different from
- * zero if it is.
- *
- * This indicator is generally set by a previous operation on the \p stream that failed.
- */
 int foug_stream_error(foug_stream_t* stream)
 {
   if (stream != NULL && stream->error_func != NULL)
@@ -75,39 +58,16 @@ int foug_stream_error(foug_stream_t* stream)
   return 0;
 }
 
-/*!
+size_t foug_stream_read(foug_stream_t* stream, void *ptr, size_t size, size_t count)
- * \brief Reads block of data from stream
- *
- * Reads an array of \p item_count elements, each one with a \p item_size of size bytes, from the
- * \p stream and stores them in the block of memory specified by \p ptr.
- *
- * The total amount of bytes read if successful is (item_size * item_count).
- *
- * \return The total number of elements successfully read is returned.
- *         If this number differs from the \p item_count argument, either a reading error occurred
- *         or the end-of-file was reached while reading. In both cases, the proper indicator is set,
- *         which can be checked with foug_stream_error() and foug_stream_at_end(), respectively.
- *         If either \p item_size or \p item_count is zero, the function returns zero and both the
- *         stream state and the content pointed by \p ptr remain unchanged.
- */
-size_t foug_stream_read(foug_stream_t* stream, void *ptr, size_t item_size, size_t item_count)
 {
   if (stream != NULL && stream->read_func != NULL)
-    return stream->read_func(stream->cookie, ptr, item_size, item_count);
+    return stream->read_func(stream->cookie, ptr, size, count);
   return 0;
 }
 
-/*!
+size_t foug_stream_write(foug_stream_t* stream, const void *ptr, size_t size, size_t count)
- * \brief Writes block of data to stream
- *
- *  Writes an array of \p item_count elements, each one with a \p item_size of size bytes, from the
- *  block of memory pointed by \p ptr to the current position in the \p stream.
- *
- *  The total amount of bytes written is (item_size * item_count).
- */
-size_t foug_stream_write(foug_stream_t* stream, const void *ptr, size_t item_size, size_t item_count)
 {
   if (stream != NULL && stream->write_func != NULL)
-    return stream->write_func(stream->cookie, ptr, item_size, item_count);
+    return stream->write_func(stream->cookie, ptr, size, count);
   return 0;
 }

src/stream.h

@@ -2,11 +2,10 @@
 #define FOUG_C_STREAM_H
 
 #include "global.h"
-#include "memory.h"
 #include <stdio.h>
 
-/*! \brief Stream that can get input from an arbitrary data source or can write output to an
+/*! Stream that can get input from an arbitrary data source or can write output to an arbitrary
- *         arbitrary data sink
+ *  data sink.
  *
  *  This is pretty much the same as
  *  <a href="http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams">
@@ -16,35 +15,93 @@
  * implemented by defining hook functions that know how to read/write the data.
  *
  */
-typedef struct
+struct foug_stream
 {
+  /*! Opaque pointer on the user stream, passed as first argument to hook functions */
   void* cookie;
 
-  foug_bool_t (*at_end_func)(void*);
+  /*! Pointer on a function that checks end-of-stream indicator.
-  int         (*error_func)(void*);
+   *
-  size_t      (*read_func)(void*, void*, size_t, size_t);
+   *  Checks whether the end-of-stream indicator associated with stream pointed by \p cookie
-  size_t      (*write_func)(void*, const void*, size_t, size_t);
+   *  is set, returning FOUG_TRUE if is.
-} foug_stream_t;
+   *
+   *  The function should behaves like C standard feof()
+   */
+  foug_bool_t (*at_end_func)(void* cookie);
+
+  /*! Pointer on a function that checks error indicator.
+   *
+   *  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()
+   */
+  int         (*error_func)(void* cookie);
+
+  /*! Pointer on a function that reads block of data from stream.
+   *
+   *  \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()
+   *
+   *  \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.
+   *
+   *  \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()
+   *
+   *  \returns The total number of elements successfully written
+   */
+  size_t      (*write_func)(void* cookie, const void* ptr, size_t size, size_t count);
+};
+
+/*! Convenient typedef for struct foug_stream */
+typedef struct foug_stream foug_stream_t;
 
 /* Initialization */
 
+/*! Installs a null stream */
 FOUG_LIB_EXPORT void foug_stream_set_null(foug_stream_t* stream);
+
+/*! Configures \p stream for standard FILE* (cookie will hold \p file) */
 FOUG_LIB_EXPORT void foug_stream_set_stdio(foug_stream_t* stream, FILE* file);
 
 /* Services */
 
+/*! Safe and convenient function for foug_stream::at_end_func().
+ *
+ *  Basically the same as : \code stream->at_end_func(stream->cookie) \endcode
+ */
 FOUG_LIB_EXPORT foug_bool_t foug_stream_at_end(foug_stream_t* stream);
 
+/*! Safe and convenient function for foug_stream::error_func().
+ *
+ *  Basically the same as : \code stream->error_func(stream->cookie) \endcode
+ */
 FOUG_LIB_EXPORT int foug_stream_error(foug_stream_t* stream);
 
+/*! Safe and convenient function for foug_stream::read_func().
+ *
+ *  Basically the same as : \code stream->read_func(stream->cookie) \endcode
+ */
 FOUG_LIB_EXPORT size_t foug_stream_read(foug_stream_t* stream,
                                         void* ptr,
-                                        size_t item_size,
+                                        size_t size,
-                                        size_t item_count);
+                                        size_t count);
 
+/*! Safe and convenient function for foug_stream::write_func().
+ *
+ *  Basically the same as : \code stream->write_func(stream->cookie) \endcode
+ */
 FOUG_LIB_EXPORT size_t foug_stream_write(foug_stream_t* stream,
                                          const void* ptr,
-                                         size_t item_size,
+                                         size_t size,
-                                         size_t item_count);
+                                         size_t count);
 
 #endif /* FOUG_C_STREAM_H */

src/task_control.c

@@ -3,13 +3,6 @@
 #include <math.h>
 #include <string.h>
 
-/*!
- * \brief Calls a function that does something with progress value \p progress_pc (eg. update
- *        a progress bar in the UI)
- *
- * The return value is important : it is used as an interruption request status. If \c true then the
- * corresponding task can continue, otherwise it should abort as soon as possible.
- */
 foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t progress_pc)
 {
   if (ctrl != NULL && ctrl->handle_progress_func != NULL)
@@ -17,12 +10,6 @@ foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t
   return 1;
 }
 
-/*!
- * \brief Converts \p value as a percentage
- *
- * \p value is assumed to be relative to the interval (range) defined by
- * [ \p range_min , \p range_max ]
- */
 uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value)
 {
   if (value >= range_max)

src/task_control.h

@@ -4,16 +4,39 @@
 #include "global.h"
 #include "memory.h"
 
-typedef struct foug_task_control
+/*! Provides control over a general task.
+ *
+ *  "Control" here means task progress handling and interruption request (abort).
+ */
+struct foug_task_control
 {
+  /*! Opaque pointer on a user task object, passed as first argument to hook functions */
   void* cookie;
-  foug_bool_t (*handle_progress_func)(void*, uint8_t);
-} foug_task_control_t;
 
-FOUG_LIB_EXPORT
+  /*! Pointer on a function that that does something with progress value \p progress (eg update
-foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t progress_pc);
+   *  a UI progress bar)
+   *
+   * The return value is important : it is used as an interruption request status. If FOUG_TRUE then
+   * the current task can continue, otherwise it should abort as soon as possible.
+   */
+  foug_bool_t (*handle_progress_func)(void* cookie, uint8_t progress);
+};
 
-FOUG_LIB_EXPORT
+/*! Convenient typedef for struct foug_task_control */
-uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value);
+typedef struct foug_task_control foug_task_control_t;
+
+/*! Safe and convenient function for foug_task_control::handle_progress_func()
+ *
+ *  Basically the same as : \code ctrl->handle_progress_func(ctrl->cookie, progress_pc) \endcode
+ */
+FOUG_LIB_EXPORT foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl,
+                                                              uint8_t progress_pc);
+
+/*! Utility function that converts \p value as a percentage
+ *
+ * \p value is assumed to be relative to the interval (range) defined by
+ * [ \p range_min , \p range_max ]
+ */
+FOUG_LIB_EXPORT uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value);
 
 #endif /* FOUG_C_TASK_CONTROL_H */