Updated documentation for the vertex_split operation

git-svn-id: http://www.openmesh.org/svnrepo/OpenMesh/trunk@688 fdac6126-5c0c-442c-9429-916003d36597

src/OpenMesh/Core/Mesh/TriMeshT.hh

@@ -167,28 +167,100 @@ public:
 
   //--- halfedge collapse / vertex split ---
 
-  /// Vertex Split: inverse operation to collapse().
+  /** \brief Vertex Split: inverse operation to collapse().
+   *
+   * Insert the new vertex at position v0. The vertex will be added
+   * as the inverse of the vertex split. The faces above the split
+   * will be correctly attached to the two new edges
+   *
+   * Before:
+   * v_l     v0     v_r
+   *  x      x      x
+   *   \           /
+   *    \         /
+   *     \       /
+   *      \     /
+   *       \   /
+   *        \ /
+   *         x
+   *         v1
+   *
+   * After:
+   * v_l    v0      v_r
+   *  x------x------x
+   *   \     |     /
+   *    \    |    /
+   *     \   |   /
+   *      \  |  /
+   *       \ | /
+   *        \|/
+   *         x
+   *         v1
+   *
+   * @param _v0_point Point position for the new point
+   * @param _v1       Vertex that will be split
+   * @param _vl       Left vertex handle
+   * @param _vr       Right vertex handle
+   * @return Newly inserted halfedge
+   */
   inline HalfedgeHandle vertex_split(Point _v0_point,  VertexHandle _v1,
                                      VertexHandle _vl, VertexHandle _vr)
   { return PolyMesh::vertex_split(add_vertex(_v0_point), _v1, _vl, _vr); }
 
+  /** \brief Vertex Split: inverse operation to collapse().
+   *
+   * Insert the new vertex at position v0. The vertex will be added
+   * as the inverse of the vertex split. The faces above the split
+   * will be correctly attached to the two new edges
+   *
+   * Before:
+   * v_l     v0     v_r
+   *  x      x      x
+   *   \           /
+   *    \         /
+   *     \       /
+   *      \     /
+   *       \   /
+   *        \ /
+   *         x
+   *         v1
+   *
+   * After:
+   * v_l    v0      v_r
+   *  x------x------x
+   *   \     |     /
+   *    \    |    /
+   *     \   |   /
+   *      \  |  /
+   *       \ | /
+   *        \|/
+   *         x
+   *         v1
+   *
+   * @param _v0 Vertex handle for the newly inserted point (Input has to be unconnected!)
+   * @param _v1 Vertex that will be split
+   * @param _vl Left vertex handle
+   * @param _vr Right vertex handle
+   * @return Newly inserted halfedge
+   */
   inline HalfedgeHandle vertex_split(VertexHandle _v0, VertexHandle _v1,
                                      VertexHandle _vl, VertexHandle _vr)
   { return PolyMesh::vertex_split(_v0, _v1, _vl, _vr); }
 
-  /// Edge split (= 2-to-4 split)
-  /// Do not call PolyMeshT function below as this does the wrong operation
-
   /** \brief Edge split (= 2-to-4 split)
    *
    * The properties of the new edges will be undefined!
    *
+   *
    * @param _eh Edge handle that should be splitted
    * @param _p  New point position that will be inserted at the edge
    * @return    Vertex handle of the newly added vertex
    */
   inline VertexHandle split(EdgeHandle _eh, const Point& _p)
-  { const VertexHandle vh = this->add_vertex(_p); Kernel::split(_eh, vh); return vh; }
+  {
+    //Do not call PolyMeshT function below as this does the wrong operation
+    const VertexHandle vh = this->add_vertex(_p); Kernel::split(_eh, vh); return vh;
+  }
 
   /** \brief Edge split (= 2-to-4 split)
    *
@@ -199,7 +271,10 @@ public:
    * @return    Vertex handle of the newly added vertex
    */
   inline VertexHandle split_copy(EdgeHandle _eh, const Point& _p)
-  { const VertexHandle vh = this->add_vertex(_p); Kernel::split_copy(_eh, vh); return vh; }
+  {
+    //Do not call PolyMeshT function below as this does the wrong operation
+    const VertexHandle vh = this->add_vertex(_p); Kernel::split_copy(_eh, vh); return vh;
+  }
 
   /** \brief Edge split (= 2-to-4 split)
    *
@@ -209,7 +284,10 @@ public:
    * @param _vh Vertex handle that will be inserted at the edge
    */
   inline void split(EdgeHandle _eh, VertexHandle _vh)
-  { Kernel::split(_eh, _vh); }
+  {
+    //Do not call PolyMeshT function below as this does the wrong operation
+    Kernel::split(_eh, _vh);
+  }
 
   /** \brief Edge split (= 2-to-4 split)
    *
@@ -219,7 +297,10 @@ public:
    * @param _vh Vertex handle that will be inserted at the edge
    */
   inline void split_copy(EdgeHandle _eh, VertexHandle _vh)
-  { Kernel::split_copy(_eh, _vh); }
+  {
+    //Do not call PolyMeshT function below as this does the wrong operation
+    Kernel::split_copy(_eh, _vh);
+  }
 
   /** \brief Face split (= 1-to-3 split, calls corresponding PolyMeshT function).
    *