Add more documentation

src/global.h

@@ -49,6 +49,7 @@ typedef unsigned long long uint64_t;
 
 /*! Typedef for boolean type */
 typedef int    foug_bool_t;
+
 /*! This enum defines true/false boolean values */
 enum foug_bool_value
 {
@@ -58,6 +59,7 @@ enum foug_bool_value
 
 /*! Typedef for 32bit real type (float) */
 typedef float  foug_real32_t;
+
 /*! Typedef for 64bit real type (double) */
 typedef double foug_real64_t;
 

src/libstl/stl_error.h

@@ -5,6 +5,7 @@
 
 enum foug_stl_rw_error
 {
+  /*! Common STL write error indicating foug_stl_geom::get_triangle_func() pointer is NULL */
   FOUG_STL_WRITE_NULL_GET_TRIANGLE_FUNC_ERROR = FOUG_STL_ERROR_TAG + 1,
 
   /* Specific error codes returned by STL_ascii read function */

src/libstl/stl_format.h

@@ -4,6 +4,7 @@
 #include "stl_global.h"
 #include "../stream.h"
 
+/*! This enums defines the various STL formats */
 enum foug_stl_format
 {
   FOUG_STL_ASCII_FORMAT,     /*!< STL ASCII (text) */

src/libstl/stla_write.c

@@ -95,7 +95,7 @@ static foug_bool_t foug_transfer_flush_buffer(foug_transfer_t* trsf, size_t n)
 
 #define _FOUG_INTERNAL_MIN(v1, v2)  ((v1) < (v2) ? (v1) : (v2))
 
-/*! \brief Write geometry in the STL ascii format
+/*! \fn int foug_stla_write(foug_stl_geom_t*, foug_transfer_t*, const char*, uint8_t)
  *
  *  \param geom Defines the custom geometry to write
  *  \param trsf Defines needed objects (stream, buffer, ...) for the writing operation
@@ -105,12 +105,6 @@ static foug_bool_t foug_transfer_flush_buffer(foug_transfer_t* trsf, size_t n)
  *  \return Error code
  *
  *  \retval FOUG_DATAX_NO_ERROR If operation successful
- *  \retval FOUG_DATAX_NULL_BUFFER_ERROR If trsf->buffer is NULL
- *  \retval FOUG_DATAX_INVALID_BUFFER_SIZE_ERROR If trsf->buffer_size is less than 512 bytes
- *  \retval FOUG_STLA_WRITE_INVALID_REAL32_PRECISION If \p real_prec is not inside [1..9]
- *  \retval FOUG_STLA_WRITE_NULL_GET_TRIANGLE_FUNC If geom->get_triangle_func is NULL
- *  \retval FOUG_DATAX_STREAM_ERROR For any writing error
- *  \retval FOUG_DATAX_TASK_STOPPED_ERROR If the operation was interrupted foug_task_control
  */
 int foug_stla_write(foug_stl_geom_t* geom,
                     foug_transfer_t* trsf,

src/libstl/stla_write.h

@@ -5,7 +5,7 @@
 #include "stl_geom.h"
 #include "../transfer.h"
 
-/* Write geometry in the STL ascii format */
+/*! Write geometry in the STL ascii format */
 FOUG_DATAX_LIBSTL_EXPORT int foug_stla_write(foug_stl_geom_t* geom,
                                              foug_transfer_t* trsf,
                                              const char*      solid_name,

src/stream.c

@@ -4,6 +4,57 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/*! \struct foug_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 foug_bool_t (*foug_stream::at_end_func)(void*)
+ *
+ *  Checks whether the end-of-stream indicator associated with stream pointed by \p cookie is set,
+ *  returning FOUG_TRUE if is.
+ *
+ *  The function should behaves like C standard [feof()]
+ *  (http://pubs.opengroup.org/onlinepubs/007904975/functions/feof.html)
+ */
+
+/*! \var int (*foug_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 (*foug_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 (*foug_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 foug_stream_set_null(foug_stream_t* stream)
 {
   memset(stream, 0, sizeof(foug_stream_t));
@@ -44,6 +95,11 @@ void foug_stream_set_stdio(foug_stream_t* stream, FILE* file)
   stream->write_func = foug_stream_stdio_write;
 }
 
+/*! \details Basically the same as :
+ *  \code
+ *    stream->at_end_func(stream->cookie)
+ *  \endcode
+ */
 foug_bool_t foug_stream_at_end(foug_stream_t* stream)
 {
   if (stream != NULL && stream->at_end_func != NULL)
@@ -51,6 +107,11 @@ foug_bool_t foug_stream_at_end(foug_stream_t* stream)
   return 0;
 }
 
+/*! \details Basically the same as :
+ *  \code
+ *    stream->error_func(stream->cookie)
+ *  \endcode
+ */
 int foug_stream_error(foug_stream_t* stream)
 {
   if (stream != NULL && stream->error_func != NULL)
@@ -58,6 +119,11 @@ int foug_stream_error(foug_stream_t* stream)
   return 0;
 }
 
+/*! \details Basically the same as :
+ *  \code
+ *    stream->read_func(stream->cookie)
+ *  \endcode
+ */
 size_t foug_stream_read(foug_stream_t* stream, void *ptr, size_t size, size_t count)
 {
   if (stream != NULL && stream->read_func != NULL)
@@ -65,6 +131,11 @@ size_t foug_stream_read(foug_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 foug_stream_write(foug_stream_t* stream, const void *ptr, size_t size, size_t count)
 {
   if (stream != NULL && stream->write_func != NULL)

src/stream.h

@@ -5,63 +5,26 @@
 #include <stdio.h>
 
 /*! Stream that can get input from an arbitrary data source or can write output to an arbitrary
- *  data sink.
- *
- *  This is pretty much the same as
- *  <a href="http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams">
- *  custom streams</a> in the GNU C Library
- *
- * It uses a cookie being basically an opaque pointer on a hidden data type. The custom stream is
- * implemented by defining hook functions that know how to read/write the data.
- *
+ *  data sink
  */
 struct foug_stream
 {
   /*! 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.
-   *
-   *  Checks whether the end-of-stream indicator associated with stream pointed by \p cookie
-   *  is set, returning FOUG_TRUE if is.
-   *
-   *  The function should behaves like C standard feof()
-   */
+  /*! Pointer on a function that checks end-of-stream indicator */
   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()
-   */
+  /*! Pointer on a function that checks error indicator */
   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
-   */
+  /*! 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);
 
-  /*! 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
-   */
+  /*! 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);
 };
 
-/*! Convenient typedef for struct foug_stream */
 typedef struct foug_stream foug_stream_t;
 
 /* Initialization */
@@ -74,31 +37,19 @@ 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
- */
+/*! Safe and convenient function for foug_stream::at_end_func() */
 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
- */
+/*! Safe and convenient function for foug_stream::error_func() */
 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
- */
+/*! Safe and convenient function for foug_stream::read_func() */
 FOUG_LIB_EXPORT size_t foug_stream_read(foug_stream_t* stream,
                                         void* ptr,
                                         size_t size,
                                         size_t count);
 
-/*! Safe and convenient function for foug_stream::write_func().
- *
- *  Basically the same as : \code stream->write_func(stream->cookie) \endcode
- */
+/*! Safe and convenient function for foug_stream::write_func() */
 FOUG_LIB_EXPORT size_t foug_stream_write(foug_stream_t* stream,
                                          const void* ptr,
                                          size_t size,

src/task_control.c

@@ -3,6 +3,20 @@
 #include <math.h>
 #include <string.h>
 
+/*! \var foug_bool_t (*foug_task_control::handle_progress_func)(void*, uint8_t)
+ *
+ *  Frequent example of hook functions is update of 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.
+ */
+
+
+/*! \details Basically the same as :
+ *  \code
+ *    ctrl->handle_progress_func(ctrl->cookie, progress_pc)
+ *  \endcode
+ */
 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)
@@ -10,6 +24,9 @@ foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t
   return 1;
 }
 
+/*! \details \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

@@ -13,30 +13,17 @@ struct foug_task_control
   /*! Opaque pointer on a user task object, passed as first argument to hook functions */
   void* cookie;
 
-  /*! Pointer on a function that that does something with progress value \p progress (eg update
-   *  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.
-   */
+  /*! Pointer on a function that that does something with progress value \p progress */
   foug_bool_t (*handle_progress_func)(void* cookie, uint8_t progress);
 };
 
-/*! Convenient typedef for struct foug_task_control */
 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
- */
+/*! Safe and convenient function for foug_task_control::handle_progress_func() */
 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 ]
- */
+/*! Utility function that converts \p value as a percentage */
 FOUG_LIB_EXPORT uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value);
 
 #endif /* FOUG_C_TASK_CONTROL_H */