better docs (#2293) [ci skip]

include/igl/copyleft/tetgen/tetgenio_to_tetmesh.h

@@ -22,6 +22,20 @@ namespace igl
   {
     namespace tetgen
     {
+      /// Convert a tetgenio to a tetmesh
+      ///
+      /// @param[in] out output of tetrahedralization
+      /// @param[out] V  #V by 3 list of mesh vertex positions
+      /// @param[out] T  #T by 4 list of mesh tet indices into V
+      /// @param[out] F  #F by 3 list of mesh triangle indices into V
+      /// @param[out] TM  #T by 1 list of material indices into R
+      /// @param[out] R  #TT list of region ID for each tetrahedron      
+      /// @param[out] N  #TT by 4 list of indices neighbors for each tetrahedron ('n')
+      /// @param[out] PT  #TV list of incident tetrahedron for a vertex ('m')
+      /// @param[out] FT  #TF by 2 list of tetrahedrons sharing a triface ('nn')
+      /// @param[out] num_regions Number of regions in output mesh
+      ///
+      /// \bug Assumes that out.numberoftetrahedronattributes == 1 or 0
       template <
         typename DerivedV, 
         typename DerivedT,

include/igl/copyleft/tetgen/tetrahedralize.h

@@ -50,6 +50,25 @@ namespace igl
       ///   2 tetgen did not crash but could not create any tets (probably there are
       ///     holes, duplicate faces etc.)
       ///   -1 other error
+      ///
+      /// \note Tetgen mixes integer region ids in with other region data `attr
+      /// = (int) in->regionlist[i + 3];`. So it's declared safe to use integer
+      /// types for `TR` since this also assumes that there's a single tet
+      /// attribute and that it's the region id.
+      ///
+      /// #### Example
+      ///
+      /// ```cpp
+      /// Eigen::MatrixXd V;
+      /// Eigen::MatrixXi F;
+      /// …
+      /// Eigen::VectorXi VM,FM;
+      /// Eigen::MatrixXd H,R;
+      /// Eigen::VectorXi TM,TR,PT;
+      /// Eigen::MatrixXi FT,TN;
+      /// int numRegions;
+      /// tetrahedralize(V,F,H,VM,FM,R,switches,TV,TT,TF,TM,TR,TN,PT,FT,numRegions);
+      /// ```
       template <
         typename DerivedV,
         typename DerivedF,