Doxygen documentation improvement

doc/doxygen/Doxyfile.in

@@ -1736,7 +1736,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1880,7 +1880,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = USE_ELAS USE_SCOTCH USE_VTK ENABLE_TESTING
+PREDEFINED             = USE_ELAS USE_SCOTCH USE_VTK ENABLE_TESTING LIBMMG3D_EXPORT
 
 # 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. The

src/mmg3d/analys_3d.c

@@ -37,10 +37,10 @@
 #include "libmmg3d_private.h"
 
 /**
- * \param mesh pointer towarad the mesh structure.
+ * \param mesh pointer towards the mesh structure.
  *
  * Set all boundary triangles to required and add a tag to detect that they are
- * not realy required.
+ * not really required.
  *
  */
 void MMG3D_set_reqBoundaries(MMG5_pMesh mesh) {

src/mmg3d/anisosiz_3d.c

@@ -1110,6 +1110,7 @@ int MMG5_defmetvol(MMG5_pMesh mesh,MMG5_pSol met,int8_t ismet) {
   isqhmin = 1./(mesh->info.hmin*mesh->info.hmin);
   isqhmax = 1./(mesh->info.hmax*mesh->info.hmax);
 
+  /** 1. no metric is provided: Set isotropic hmax size at the vertex */
   if ( !ismet ) {
 
     for (k=1; k<=mesh->ne; k++) {
@@ -1122,8 +1123,6 @@ int MMG5_defmetvol(MMG5_pMesh mesh,MMG5_pSol met,int8_t ismet) {
         ppt = &mesh->point[ip];
         if ( ppt->flag || ppt->tag & MG_BDY || !MG_VOK(ppt) ) continue;
 
-        /** 1. no metric is provided: Set isotropic hmax size at the vertex */
-
         /** First step: search for local parameters */
         if ( mesh->info.parTyp ) {
           isqhmax = mesh->info.hmax;

src/mmg3d/boulep_3d.c

@@ -333,7 +333,7 @@ int MMG5_boulenm(MMG5_pMesh mesh,MMG5_int start,int ip,int iface,
  * \param start tetra index.
  * \param ip point index.
  * \param t computed tangent vector.
- * \return 0 when more than two NOM points are attached to ip, 1 if sucess.
+ * \return 0 when more than two NOM points are attached to ip, 1 if success.
  *
  * Travel the ball of the internal non manifold point ip in tetra start
  * and calculate the tangent vector to the underlying curve.
@@ -602,7 +602,7 @@ int MMG5_boulernm(MMG5_pMesh mesh,MMG5_Hash *hash,MMG5_int start,int ip,MMG5_int
  *   - \a listv[k] = 4* tet index + index of point surfacic ball.
  *   - \a lists[k] = 4* tet index + index of boundary face.
  *
- * \warning Don't work for a non-manifold point if \a start has an adjacent
+ * \warning Does not work for a non-manifold point if \a start has an adjacent
  * through \a iface (for example : a non-manifold subdomain). Thus, if \a ip is
  * non-manifold, must be called only if \a start has no adjacent through iface.
  *

src/mmg3d/colver_3d.c

@@ -236,19 +236,16 @@ MMG5_int MMG3D_unfold_shell(MMG5_pMesh  mesh,MMG5_int start,MMG5_int end, MMG5_i
 /**
  * \param mesh pointer to the mesh structure.
  * \param k index of the starting tetra.
- * \param iface local index of the starting face in the tetra \a k.
- * \param ideg local index of the starting edge in the face \a iface.
- * \param lists surfacic ball of p.
- * \param ilists number of elements in the surfacic ball of p.
+ * \param iface local index of starting face in the tetra \a k.
+ * \param iedg local index of starting edge in the face \a iface (local num).
+ * \param lists surfacic ball of point \a np.
+ * \param ilists number of elements in the surfacic ball of point \a np.
  *
  * \return 0 if the check of the topology fails, 1 if success, -1 if the
  * function fails.
  *
- * Topological check on the surface ball of np and nq in collapsing np->nq ;
- *  iface = boundary face on which lie edge iedg - in local face num.  (pq, or
- *  ia in local tet notation). See the Mmg Google
- *  Drive/Documentation/mmg3d/topchkcol_bdy3D.pdf for a picture of the
- *  configuration.
+ * Topological checks of surfacic ball of \a np and \a nq in collapsing
+ * \a np over \a nq.
  *
  */
 static int
@@ -496,33 +493,35 @@ int MMG3D_get_shellEdgeTag(MMG5_pMesh  mesh,MMG5_int start, int8_t ia,uint16_t *
 /**
  * \param mesh pointer to the mesh structure.
  * \param met pointer to the metric structure.
- * \param k index of element in which we collapse.
- * \param iface face through wich we perform the collapse
- * \param iedg edge to collapse (in local face num)
- * \param listv pointer to the list of the tetra in the ball of \a p0.
- * \param ilistv number of tetra in the ball of \a p0.
- * \param lists pointer to the surfacic ball of \a p0.
- * \param ilists number of tetra in the surfacic ball of \a p0.
- * \param refmin reference of one of the two subdomains in presence
- * \param refplus reference of the other subdomain in presence
+ * \param k index of element from which collapse occurs.
+ * \param iface face through which collapse is performed.
+ * \param iedg edge to collapse (in local face num).
+ * \param listv pointer to the list of tetra in ball of \a p0.
+ * \param ilistv number of tetra in ball of \a p0.
+ * \param lists pointer to surfacic ball of \a p0.
+ * \param ilists number of tetra in surfacic ball of \a p0.
+ * \param refmin reference of one of the two subdomains in presence.
+ * \param refplus reference of the other subdomain in presence.
  * \param typchk  typchk type of checking permformed for edge length
  * (hmax or MMG3D_LLONG criterion).
- * \param isnm 1 if edge is non-manifold
- * \param isnmint 1 if ip is an internal non manifold point;
+ * \param isnm 1 if edge is non-manifold.
+ * \param isnmint 1 if ip is an internal non manifold point.
  *
  * \return ilistv if success, 0 if the point cannot be collapsed, -1 if fail.
  *
- * Check whether collapse ip -> iq could be performed, ip boundary point;
- *  'mechanical' tests (positive jacobian) are not performed here ;
- *  iface = boundary face on which lie edge iedg - in local face num.
- *  (pq, or ia in local tet notation).
- * If isnm is 1, the collapse occurs along an external MG_NOM edge.
- * If isnmint is 1, ip is an internal non manifold point and dont have normals.
- *  In this last case, \a lists, \a ilists \a refmin, \a refplus and \a isnm
- *  variables aren't used (we neither have a surfacic ball nor "positive" and
- *  "negative" volumes)
+ * Check whether collapse point \a ip over \a iq could be performed, where
+ * \a ip is a boundary point.
  *
- * \remark we don't check edge lengths.
+ * 'Mechanical' tests (positive jacobian) are not performed here.
+ *
+ * If \a isnm is 1, the collapse occurs along an external MG_NOM edge.
+ *
+ * If \a isnmint is 1, ip is an internal non manifold point and does not have
+ * normals. In this last case, \a lists, \a ilists \a refmin, \a refplus and
+ * \a isnm variables aren't used (we neither have a surfacic ball nor
+ * "positive" and "negative" volumes)
+ *
+ * \remark edge lengths are not checked.
  */
 int MMG5_chkcol_bdy(MMG5_pMesh mesh,MMG5_pSol met,MMG5_int k,int8_t iface,
                     int8_t iedg,int64_t *listv,int ilistv,MMG5_int *lists,int ilists,
@@ -605,7 +604,7 @@ int MMG5_chkcol_bdy(MMG5_pMesh mesh,MMG5_pSol met,MMG5_int k,int8_t iface,
       }
 
       if ( nbbdy == 4 ) {
-        /* Only one element in the domain: we don't want to delete it */
+        /* Only one element in the domain: it cannot be deleted */
         return 0;
       }
       else if ( nbbdy == 3 ) {
@@ -632,7 +631,7 @@ int MMG5_chkcol_bdy(MMG5_pMesh mesh,MMG5_pSol met,MMG5_int k,int8_t iface,
 
         /*  Avoid surface crimping: check that the collapse doesn't merge 3
          *  bdy edge along a non bdy face: we have to check the edge of each
-         *  shell because some MG_BDY tags may be missings due to the creation
+         *  shell because some MG_BDY tags may be missing due to the creation
          *  of an xtetra during a previous collapse */
         if ( (!pt->xt) || !(pxt->ftag[i] & MG_BDY) ) {
           uint16_t  tag0,tag1,tag2;

src/mmg3d/hash_3d.c

@@ -1538,7 +1538,7 @@ int MMG5_bdryTria(MMG5_pMesh mesh, MMG5_int ntmesh) {
  * \param mesh pointer to the mesh structure.
  * \return 1 if success, 0 otherwise.
  *
- * - Remove double triangles from tria array.
+ * - Remove duplicate triangles from tria array.
  *
  * - Remove triangles that do not belong to a boundary (non opnbdy mode) from
  *   tria array.
@@ -1547,13 +1547,13 @@ int MMG5_bdryTria(MMG5_pMesh mesh, MMG5_int ntmesh) {
  * Count the number of faces in mesh and compare this number to the number of
  *   given triangles.
  *
- * - If the founded number exceed the given one, add the missing
+ * - If found number exceeds given one, add the missing
  *   boundary triangles (call to MMG5_bdryTria). Do nothing otherwise.
  *
  * - Fill the adjacency relationship between prisms and tetra (fill adjapr with
  *   a negative value to mark this special faces).
  *
- * - Set to required the triangles at interface betwen prisms and tet.
+ * - Set triangles at interface betwen prisms and tet to required.
  *
  */
 int MMG5_chkBdryTria(MMG5_pMesh mesh) {
@@ -1585,11 +1585,11 @@ int MMG5_chkBdryTria(MMG5_pMesh mesh) {
 
 /**
  * \param mesh pointer to the mesh structure.
- * \param ntmesh number of boundary triangles in the mesh.
- * \param ntpres number of preserved boundaries in the mesh.
+ * \param ntmesh number of boundary triangles.
+ * \param ntpres number of preserved boundaries (open boundary mode).
  * \return 0 if failed, 1 if success.
  *
- * Step 1 of MMG5_chkBdryTria : scan the mesh and count the boundaries
+ * Step 1 of MMG5_chkBdryTria : scan the mesh and count the boundaries.
  *
  */
 int MMG5_chkBdryTria_countBoundaries(MMG5_pMesh mesh, MMG5_int *ntmesh, MMG5_int *ntpres) {

src/mmg3d/isosiz_3d.c

@@ -81,10 +81,10 @@ inline double MMG5_lenedgCoor_iso(double *ca,double *cb,double *ma,double *mb) {
  * \param hmin minimal edge size.
  * \param hmax maximal edge size.
  * \param hausd hausdorff value.
- * \return the isotropic size at the point if success, FLT_MAX if fail.
+ * \return isotropic size at the point if success, FLT_MAX if fail.
  *
  * Define isotropic size at regular point nump, whose surfacic ball is provided
- * and update metric at 'regular' non-manifold points of the surfacic ball of
+ * and update metric at "regular" non-manifold points of the surfacic ball of
  * point.
  *
  */
@@ -556,8 +556,8 @@ int MMG3D_sum_reqEdgeLengthsAtPoint(MMG5_pMesh mesh,MMG5_pSol met,MMG5_Hash *has
  *
  * \return 0 if fail, 1 otherwise
  *
- * Compute the metric at points on trequired adges as the mean of the lengths of
- * the required eges to which belongs the point. The processeed points are
+ * Compute metric at points on required edges as the mean of lengths of
+ * the required edges to which the point belongs. Processeed points are
  * marked with flag 3.
  *
  */
@@ -654,9 +654,12 @@ int MMG3D_set_metricAtPointsOnReqEdges ( MMG5_pMesh mesh,MMG5_pSol met,int8_t is
  * \param met pointer to the metric structure.
  * \return 0 if fail, 1 otherwise.
  *
- * Define isotropic size map at all boundary vertices of the mesh, associated
- * with geometric approx, and prescribe hmax at the internal vertices Field h of
- * Point is used, to store the prescribed size (not inverse, squared,...)
+ * Define isotropic size map at mesh vertices, whether or not metric data
+ * is provided by the user. Vertices are treated in the following order:
+ *  - required vertices,
+ *  - regular internal vertices,
+ *  - regular surface vertices,
+ *  - ridge/edge surface vertices.
  *
  */
 int MMG3D_defsiz_iso(MMG5_pMesh mesh,MMG5_pSol met) {
@@ -887,7 +890,7 @@ int MMG3D_defsiz_iso(MMG5_pMesh mesh,MMG5_pSol met) {
     }
   }
 
-  /** Step 3: size at regular surface points */
+  /** 2) Size at regular surface points */
   for (k=1; k<=mesh->ne; k++) {
     pt = &mesh->tetra[k];
     // Warning: why are we skipped the tetra with negative refs ?

src/mmg3d/mmg3d1.c

@@ -47,11 +47,11 @@ extern int8_t ddb;
  * \param mesh pointer to mesh
  * \param ppt pointer to point whose geom data have to be updated
  * \param tag point tag
- * \param nmref ref that has to be setted at point \a ppt if point is non-manifold
- * \param edgref ref that has to be setted at point \a ppt if point is manifold (edg ref)
- * \param no1 normal that has to be setted at point \a ppt (if needed)
- * \param no2 normal that has to be setted at point \a ppt (if needed)
- * \param to tangent that has to be setted at point \a ppt (if needed)
+ * \param nmref ref that has to be set at point \a ppt if point is non-manifold
+ * \param edgref ref that has to be set at point \a ppt if point is manifold (edg ref)
+ * \param no1 normal that has to be set at point \a ppt (if needed)
+ * \param no2 normal that has to be set at point \a ppt (if needed)
+ * \param to tangent that has to be set at point \a ppt (if needed)
  *
  * Set geometric info (ref, tag, normals and tangent) at point \a ppt.
  *
@@ -883,8 +883,8 @@ MMG5_int MMG5_movtet(MMG5_pMesh mesh,MMG5_pSol met, MMG3D_pPROctree PROctree,
 /**
  * \param mesh pointer to the mesh structure.
  * \param met pointer to the metric structure.
- * \param typchk type of checking permformed for edge length (hmin or LSHORT criterion).
- * \return a negative value in case of failure, number of collapsed points otherwise.
+ * \param typchk type of edge length criterion (hmin or LSHORT criterion).
+ * \return negative value in case of failure, number of collapsed points otherwise.
  *
  * Attempt to collapse short edges.
  *
@@ -904,7 +904,7 @@ static MMG5_int MMG5_coltet(MMG5_pMesh mesh,MMG5_pSol met,int8_t typchk) {
   int16_t         isnmint;
 
   int8_t          i,j,ip,iq;
-  int             ier, bsret;   // function return values/error codes
+  int             ier, bsret;
 
   nc = nnm = 0;
 
@@ -935,7 +935,7 @@ static MMG5_int MMG5_coltet(MMG5_pMesh mesh,MMG5_pSol met,int8_t typchk) {
 
         if ( p0->flag == base ) {
           /* I think that we can't pass here because we break the loop when base
-           * is setted and just after we increment it */
+           * is set and just after we increment it */
           assert(0);
           continue;
         }
@@ -1890,8 +1890,8 @@ int8_t MMG3D_build_bezierEdge(MMG5_pMesh mesh,MMG5_int k,
  * \param p0 pointer to first extremity of edge \a ied (to fill)
  * \param p1 pointer to second extremity of edge \a ied (to fill)
  *
- * Search a face from wich we car reach edge \a ied. If a boundary face with
- * good orientation exists it is choosed prior to another face, otherwise, if
+ * Search a face from which we can reach edge \a ied. If a boundary face with
+ * good orientation exists it is chosen prior to another face, otherwise, if
  * possible, we choose a boundary face. Fill data needed to work on edge.
  *
  */

src/mmg3d/mmg3d1_delone.c

@@ -65,13 +65,13 @@ int8_t  ddb;
  *
  * \return -1 for strong failure.
  *
- * \return 0 if edge cannot be splitted and if we want to pass to next loop step
+ * \return 0 if edge cannot be split and if we want to pass to next loop step
  * (next element or next tetra edge)
  *
- * \return 1 if edge cannot be splitted and we want to try to collapse too long
+ * \return 1 if edge cannot be split and we want to try to collapse too long
  * edge.
  *
- * \return 2 if edge has been splitted and we want to treat next element.
+ * \return 2 if edge has been split and we want to treat next element.
  *
  * \return 3 if nothing has been done (no error but no split either).
  *
@@ -160,7 +160,7 @@ int MMG3D_mmg3d1_delone_split(MMG5_pMesh mesh, MMG5_pSol met,
 
     /* Simulation only if intmet call is successful */
     /* simbulgept needs a valid tangent at ridge point (to build ridge metric in
-     * order to comute edge lengths). Thus we need to store the geometric info of
+     * order to compute edge lengths). Thus we need to store the geometric info of
      * point here. */
     ppt = &mesh->point[ip];
     MMG3D_set_geom(mesh,ppt,tag,ref,pxt->ref[i],no1,no2,to);
@@ -393,7 +393,7 @@ int MMG3D_mmg3d1_delone_splcol(MMG5_pMesh mesh, MMG5_pSol met,
   }
 
   /** If unable to treat edge with ier==1 return value or if edge has
-   * not been splitted but slpit_delone has not raised any error: try to
+   * not been splitted but split_delone has not raised any error: try to
    * collapse short edge. */
 
   /** 2. Try to merge small edge: if collapse is not possible, pass to
@@ -948,7 +948,7 @@ int MMG5_optet(MMG5_pMesh mesh, MMG5_pSol met,MMG3D_pPROctree PROctree) {
  * \param mesh pointer to the mesh structure.
  * \param met pointer to the metric structure.
  * \param PROctree pointer to the PROctree structure.
- * \param permNodGlob if provided, strore the global permutation of nodes
+ * \param permNodGlob if provided, store the global permutation of nodes
  * \return 0 if failed, 1 otherwise.
  *
  * Analyze tetrahedra and split long / collapse short, according to

src/mmg3d/tools_3d.c

@@ -85,9 +85,18 @@ inline int MMG5_directsurfball(MMG5_pMesh mesh, MMG5_int ip, MMG5_int *list, int
     return 2;
 }
 
-/** If need be, reorder the surfacic ball of point ip, so that its first element has
-    edge (p,q) (nump,q = global num) as edge MMG5_iprv2[ip] of face iface.
-    return 2 = orientation reversed, 1 otherwise */
+/**
+ * \param mesh pointer to mesh structure.
+ * \param nump point to collapse (global num).
+ * \param numq point receiving collapse (global num).
+ * \param list pointer to surfacic ball of \a nump.
+ * \param ilist number of elements in surfacic ball.
+ * \return 2 if ball reordered, 1 otherwise.
+ *
+ * Reorder surfacic ball of point \a ip, so that its first element has
+ * edge \a (p,q) as edge \a MMG5_iprv2[ip] of face \a iface.
+ *
+ */
 int MMG5_startedgsurfball(MMG5_pMesh mesh,MMG5_int nump,MMG5_int numq,MMG5_int *list,int ilist) {
     MMG5_pTetra pt;
     int         l;
@@ -105,7 +114,7 @@ int MMG5_startedgsurfball(MMG5_pMesh mesh,MMG5_int nump,MMG5_int numq,MMG5_int *
 
     ipt = MMG5_idirinv[iface][ip]; // index of ip in face iface
     ipt = MMG5_inxt2[ipt];         // next index in this face
-    ipt = MMG5_idir[iface][ipt];  // index of this point in local num of tetra
+    ipt = MMG5_idir[iface][ipt];   // index of this point in local num of tetra
 
     if(pt->v[ipt] == numq) return 1;