[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,31 +91,34 @@ 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;
-  int           connected_edges;
-  int           connected_facets_1_edge;
-  int           connected_facets_2_edge;
-  int           connected_facets_3_edge;
-  int           facets_w_1_bad_edge;
-  int           facets_w_2_bad_edge;
-  int           facets_w_3_bad_edge;
-  int           original_num_facets;
-  int           edges_fixed;
-  int           degenerate_facets;
-  int           facets_removed;
-  int           facets_added;
-  int           facets_reversed;
-  int           backwards_edges;
+  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;         /**< how many edges have been connected by ADMesh */
+  int           connected_facets_1_edge; /**< how many facets are connected by at least 1 edge, get's calculated during stl_check_facets_nearby() */
+  int           connected_facets_2_edge; /**< how many facets are connected by at least 2 edges, get's calculated during stl_check_facets_nearby() */
+  int           connected_facets_3_edge; /**< how many facets are connected by all 3 edges, get's calculated during stl_check_facets_nearby() */
+  int           facets_w_1_bad_edge;     /**< how many facets have exactly 1 unconnected edge, get's calculated during stl_repair() */
+  int           facets_w_2_bad_edge;     /**< how many facets have exactly 2 unconnected edges, get's calculated during stl_repair() */
+  int           facets_w_3_bad_edge;     /**< how many facets have exactly 3 unconnected edges, get's calculated during stl_repair() */
+  int           original_num_facets;     /**< original number of facets when the file was loaded */
+  int           edges_fixed;             /**< how many edges were fixed by ADMesh */
+  int           degenerate_facets;       /**< number of removed degenerate facets */
+  int           facets_removed;          /**< number of removed degenerate facets */
+  int           facets_added;            /**< number of facets removed by stl_remove_unconnected_facets() */
+  int           facets_reversed;         /**< number of facets reversed by stl_fix_normal_directions() */
+  int           backwards_edges;         /**< number of edges that are backwards counted during stl_verify_neighbors() */
   int           normals_fixed;
   int           number_of_parts;
   int           malloced;
@@ -120,21 +129,23 @@ typedef struct {
   int           shared_malloced;
 } stl_stats;
 
+/** STL file.
+ * The main structure representing the mesh.
+ * All functions take reference to this as a first argument. */
 typedef struct {
-  FILE          *fp;
-  stl_facet     *facet_start;
-  stl_edge      *edge_start;
-  stl_hash_edge **heads;
-  stl_hash_edge *tail;
-  int           M;
-  stl_neighbors *neighbors_start;
-  v_indices_struct *v_indices;
-  stl_vertex    *v_shared;
-  stl_stats     stats;
-  char          error;
+  FILE          *fp;              /**< pointer to associated file */
+  stl_facet     *facet_start;     /**< array of facets */
+  stl_edge      *edge_start;      /**< array of edges populated by stl_verify_neighbors() */
+  stl_hash_edge **heads;          /**< head of linked list of edges, used internally by some repairs */
+  stl_hash_edge *tail;            /**< tail of linked list of edges, used internally by some repairs */
+  int           M;                /**< magic variable, used internally by some repairs */
+  stl_neighbors *neighbors_start; /**< array of neighbors populated by various repairs  */
+  v_indices_struct *v_indices;    /**< internal array used by stl_generate_shared_vertices() */
+  stl_vertex    *v_shared;        /**< vertices array used by stl_generate_shared_vertices() */
+  stl_stats     stats;            /**< statistics about the mesh */
+  char          error;            /**< error flag, when something went wrong, this is not 0 */
 } stl_file;
 
-
 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);