Add more doxygen documentation

src/c/libstl/stla_write.c

@@ -88,9 +88,26 @@ static foug_bool_t foug_tansfer_flush_buffer(foug_transfer_t* trsf, size_t n)
   return foug_stream_write(&trsf->stream, trsf->buffer, sizeof(char), n) == n;
 }
 
+/*! \brief Write geometry in the STL ascii format
+ *
+ *  \param geom Defines the custom geometry to write
+ *  \param trsf Defines needed objects (stream, buffer, ...) for the writing operation
+ *  \param real32_prec The maximum number of significant digits
+ *
+ *  \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_COUNT_FUNC If geom->get_triangle_count_func is NULL
+ *  \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_stla_geom_output_t* geom,
                     foug_transfer_t* trsf,
-                    uint8_t real32_precision)
+                    uint8_t real32_prec)
 {
   size_t solid_count = 0;
   size_t total_facet_count = 0;
@@ -101,7 +118,7 @@ int foug_stla_write(foug_stla_geom_output_t* geom,
   char coords_format[64];
   int error = FOUG_DATAX_NO_ERROR;
 
-  if (real32_precision == 0 || real32_precision > 9)
+  if (real32_prec == 0 || real32_prec > 9)
     return FOUG_STLA_WRITE_INVALID_REAL32_PRECISION;
   if (buffer_iterator == NULL)
     return FOUG_DATAX_NULL_BUFFER_ERROR;
@@ -114,11 +131,11 @@ int foug_stla_write(foug_stla_geom_output_t* geom,
 
   {
     char* coords_format_iterator = coords_format;
-    coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_precision);
+    coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_prec);
     coords_format_iterator = foug_write_nspaces(coords_format_iterator, 2);
-    coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_precision);
+    coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_prec);
     coords_format_iterator = foug_write_nspaces(coords_format_iterator, 2);
-    coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_precision);
+    coords_format_iterator = foug_write_stdio_format(coords_format_iterator, real32_prec);
     /* TODO: check the "format" string can contain the given precision */
   }
 

src/c/libstl/stla_write.h

@@ -5,25 +5,26 @@
 #include "stl_triangle.h"
 #include "../transfer.h"
 
-/* foug_stla_geom_output */
+/* Custom geometry expressed with STL ascii interface */
 typedef struct foug_stla_geom_output foug_stla_geom_output_t;
 struct foug_stla_geom_output
 {
   void*  cookie;
-  size_t (*get_solid_count_func)   (foug_stla_geom_output_t*); /* Optional */
+
+  size_t (*get_solid_count_func)   (foug_stla_geom_output_t*); /* Optional (if NULL solid_count == 1) */
   void   (*get_solid_name)         (foug_stla_geom_output_t*, size_t, char*); /* Optional */
   size_t (*get_triangle_count_func)(foug_stla_geom_output_t*, size_t);
   void   (*get_triangle_func)      (foug_stla_geom_output_t*, size_t, size_t, foug_stl_triangle_t*);
 };
 
-/* foug_stla_write() */
+/* Write geometry in the STL ascii format */
 FOUG_DATAX_LIBSTL_EXPORT int foug_stla_write(foug_stla_geom_output_t* geom,
                                              foug_transfer_t*         trsf,
-                                             uint8_t                  real32_precision);
+                                             uint8_t                  real32_prec);
 
 /* Specific error codes returned by foug_stla_write() */
-#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_COUNT_FUNC 1
+#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_COUNT_FUNC 1 /*!< get_triangle_count_func is null */
-#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_FUNC       2
+#define FOUG_STLA_WRITE_NULL_GET_TRIANGLE_FUNC       2 /*!< get_triangle_func is null */
-#define FOUG_STLA_WRITE_INVALID_REAL32_PRECISION     3
+#define FOUG_STLA_WRITE_INVALID_REAL32_PRECISION     3 /*!< real32_prec is not in [1..9] */
 
 #endif /* FOUG_DATAX_C_LIBSTL_STLA_WRITE_H */

src/c/libstl/stlb_read.h

@@ -11,10 +11,10 @@ typedef struct foug_stlb_geom_input foug_stlb_geom_input_t;
 struct foug_stlb_geom_input
 {
   void* cookie;
-  void  (*process_header_func)       (foug_stlb_geom_input_t*, const uint8_t*);
+  void  (*process_header_func)       (foug_stlb_geom_input_t*, const uint8_t*); /* Optional */
-  void  (*begin_triangles_func)      (foug_stlb_geom_input_t*, uint32_t);
+  void  (*begin_triangles_func)      (foug_stlb_geom_input_t*, uint32_t);       /* Optional */
   void  (*process_next_triangle_func)(foug_stlb_geom_input_t*, const foug_stlb_triangle_t*);
-  void  (*end_triangles_func)        (foug_stlb_geom_input_t*);
+  void  (*end_triangles_func)        (foug_stlb_geom_input_t*);                 /* Optional */
 };
 
 /* foug_stlb_read() */

src/c/memory.h

@@ -3,7 +3,10 @@
 
 #include <string.h>
 
+/*! Type alias for "pointer on function that allocates memory" (like standard malloc()) */
 typedef void* (*foug_malloc_func_t)(size_t);
+
+/*! Type alias for "pointer on function that frees memory" (like standard free()) */
 typedef void  (*foug_free_func_t)(void*);
 
 #endif /* FOUG_C_MEMORY_H */

src/c/stream.c

@@ -5,7 +5,7 @@
 #include <stdlib.h>
 
 /*!
- * \brief Install a null stream
+ * \brief Installs a null stream
  */
 void foug_stream_set_null(foug_stream_t* stream)
 {
@@ -39,7 +39,7 @@ static size_t foug_stream_stdio_write(foug_stream_t* stream,
 }
 
 /*!
- * \brief Create a stream for standard FILE*
+ * \brief Configures \p stream for standard FILE*
  */
 void foug_stream_set_stdio(foug_stream_t* stream, FILE* file)
 {
@@ -50,6 +50,9 @@ 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)
@@ -58,7 +61,7 @@ foug_bool_t foug_stream_at_end(foug_stream_t* stream)
 }
 
 /*!
- * \brief Check error indicator
+ * \brief Checks error indicator
  *
  * Checks if the error indicator associated with \p stream is set, returning a value different from
  * zero if it is.
@@ -73,7 +76,7 @@ int foug_stream_error(foug_stream_t* stream)
 }
 
 /*!
- * \brief Read block of data from stream
+ * \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.
@@ -95,7 +98,7 @@ size_t foug_stream_read(foug_stream_t* stream, void *ptr, size_t item_size, size
 }
 
 /*!
- * \brief Write block of data to stream
+ * \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.

src/c/stream.h

@@ -5,11 +5,23 @@
 #include "memory.h"
 #include <stdio.h>
 
-/* foug_stream */
 typedef struct foug_stream foug_stream_t;
+
+/*! \brief 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.
+ *
+ */
 struct foug_stream
 {
   void* cookie;
+
   foug_bool_t (*at_end_func)(foug_stream_t*);
   int32_t     (*error_func)(foug_stream_t*);
   size_t      (*read_func)(foug_stream_t*, void*, size_t, size_t);

src/c/task_control.c

@@ -3,6 +3,13 @@
 #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)
@@ -10,6 +17,12 @@ 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)