[Unfinished] Document data types

docs/Doxyfile

@@ -5,6 +5,10 @@ JAVADOC_AUTOBRIEF      = YES
 QT_AUTOBRIEF           = YES
 INPUT                  = ../src/admesh
 GENERATE_LATEX         = NO
+GENERATE_HTML          = NO
 GENERATE_XML           = YES
 XML_OUTPUT             = _doxyxml
+OPTIMIZE_OUTPUT_FOR_C  = YES
+TYPEDEF_HIDES_STRUCT   = YES
+EXTRACT_ALL            = YES
 QUIET                  = YES

src/stl.h

@@ -40,12 +40,14 @@ extern "C" {
 #define ASCII_LINES_PER_FACET  7
 #define SIZEOF_EDGE_SORT       24
 
+/** Vertex of a facet, defined by 3D coordinates */
 typedef struct {
   float x;
   float y;
   float z;
 } stl_vertex;
 
+/** Normal vector of a facet, defined by 3D coordinates */
 typedef struct {
   float x;
   float y;
@@ -54,19 +56,23 @@ typedef struct {
 
 typedef char stl_extra[2];
 
+/** Facet, one triangle of the mesh */
 typedef struct {
-  stl_normal normal;
-  stl_vertex vertex[3];
-  stl_extra  extra;
+  stl_normal normal; /**< normal vector*/
+  stl_vertex vertex[3]; /**< 3 vertices*/
+  stl_extra  extra; /**< extra data*/
 } stl_facet;
+
 #define SIZEOF_STL_FACET       50
 
+/** Type of STL file */
 typedef enum {binary, ascii, inmemory} stl_type;
 
+/** Edge between two vertices */
 typedef struct {
-  stl_vertex p1;
-  stl_vertex p2;
-  int        facet_number;
+  stl_vertex p1; /**< start vertex */
+  stl_vertex p2; /**< end vertex */
+  int        facet_number; /**< id of facet this edge belongs to */
 } stl_edge;
 
 typedef struct stl_hash_edge {
@@ -85,17 +91,20 @@ typedef struct {
   int   vertex[3];
 } v_indices_struct;
 
+/** Statistics about the STL mesh.
+ * Some of them are populated on stl_open() and after some operations,
+ * others, such as volume, have to be calculated by appropriate functions. */
 typedef struct {
-  char          header[81];
-  stl_type      type;
-  int           number_of_facets;
-  stl_vertex    max;
-  stl_vertex    min;
-  stl_vertex    size;
-  float         bounding_diameter;
-  float         shortest_edge;
-  float         volume;
-  unsigned      number_of_blocks;
+  char          header[81]; /**< header of the STL file */
+  stl_type      type; /**< type of the STL file */
+  int           number_of_facets; /**< total number of facets */
+  stl_vertex    max; /**< maximal dimensions of the mesh */
+  stl_vertex    min; /**< minimal dimensions of the mesh */
+  stl_vertex    size; /**< size of the bounding box */
+  float         bounding_diameter; /**< diameter of the bounding box */
+  float         shortest_edge; /**< length of the shortest edge */
+  float         volume; /**< volume of the mesh, has to be calculated by stl_calculate_volume() */
+  unsigned      number_of_blocks; /**< should be number of blocks, but is never set */
   int           connected_edges;
   int           connected_facets_1_edge;
   int           connected_facets_2_edge;
@@ -134,7 +143,7 @@ typedef struct {
   char          error;
 } stl_file;
 
-
+/** fooo */
 extern void stl_open(stl_file *stl, char *file);
 extern void stl_close(stl_file *stl);
 extern void stl_stats_out(stl_file *stl, FILE *file, char *input_file);