added documentation for the line search routines

Former-commit-id: 57f9db6fb41ddd85fcb724ca7e9b220e686bf62f

include/igl/flip_avoiding_line_search.h

@@ -13,13 +13,31 @@
 
 namespace igl
 {
-  // TODO DOCUMENTATION MISSING
+  // A bisection line search for a mesh based energy that avoids triangle flips as suggested in 
+  // 		"Bijective Parameterization with Free Boundaries" (Smith J. and Schaefer S., 2015).
+  //
+  // The user specifies an initial vertices position (that has no flips) and target one (that my have flipped triangles).
+  // This method first computes the largest step in direction of the destination vertices that does not incur flips,
+  // and then minimizes a given energy using this maximal step and a bisection linesearch (see igl::line_search).
+  //
+  // Supports both triangle and tet meshes.
+  //
+  // Inputs:
+  //   F  #F by 3/4 				list of mesh faces or tets
+  //   cur_v  						#V by dim list of variables
+  //   dst_v  						#V by dim list of target vertices. This mesh may have flipped triangles
+  //   energy       			    A function to compute the mesh-based energy (return an energy that is bigger than 0)
+  //   cur_energy(OPTIONAL)         The energy at the given point. Helps save redundant computations. 
+  //							    This is optional. If not specified, the function will compute it.
+  // Outputs:
+  //		cur_v  						#V by dim list of variables at the new location
+  // Returns the energy at the new point
   IGL_INLINE double flip_avoiding_line_search(
     const Eigen::MatrixXi F,
     Eigen::MatrixXd& cur_v,
     Eigen::MatrixXd& dst_v,
     std::function<double(Eigen::MatrixXd&)> energy,
-    double cur_energy);
+    double cur_energy = -1);
 
 }
 

include/igl/line_search.h

@@ -13,13 +13,25 @@
 
 namespace igl
 {
-  // TODO DOCUMENTATION MISSING
+  // Implement a bisection linesearch to minimize a mesh-based energy on vertices given at 'x' at a search direction 'd',
+  // with initial step size. Stops when a point with lower energy is found, or after maximal iterations have been reached.
+  //
+  // Inputs:
+  //   x  						#X by dim list of variables
+  //   d  						#X by dim list of a given search direction
+  //   i_step_size  			initial step size
+  //   energy       			A function to compute the mesh-based energy (return an energy that is bigger than 0)
+  //   cur_energy(OPTIONAL)     The energy at the given point. Helps save redundant computations. 
+  //							This is optional. If not specified, the function will compute it.
+  // Outputs:
+  //		x  						#X by dim list of variables at the new location
+  // Returns the energy at the new point 'x'
   IGL_INLINE double line_search(
     Eigen::MatrixXd& x,
     const Eigen::MatrixXd& d,
-    double step_size,
+    double i_step_size,
     std::function<double(Eigen::MatrixXd&)> energy,
-    double cur_energy);
+    double cur_energy = -1);
 
 }