From b1f4e2b4db0065cd4243e5645c2157314e126ddc Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Sat, 30 Mar 2013 08:54:50 +0000
Subject: [PATCH] code comments: bmesh operator doxy header descriptions.

---
 source/blender/bmesh/operators/bmo_beautify.c       | 13 +++++++++++++
 source/blender/bmesh/operators/bmo_bevel.c          |  2 ++
 source/blender/bmesh/operators/bmo_connect.c        |  2 ++
 source/blender/bmesh/operators/bmo_create.c         |  6 ++++--
 source/blender/bmesh/operators/bmo_dissolve.c       |  2 ++
 source/blender/bmesh/operators/bmo_dupe.c           | 13 ++++++-------
 source/blender/bmesh/operators/bmo_edgeloop_fill.c  |  2 ++
 source/blender/bmesh/operators/bmo_edgenet.c        |  2 ++
 source/blender/bmesh/operators/bmo_extrude.c        |  2 ++
 source/blender/bmesh/operators/bmo_hull.c           |  2 ++
 source/blender/bmesh/operators/bmo_inset.c          |  5 +++++
 source/blender/bmesh/operators/bmo_join_triangles.c |  5 +++++
 source/blender/bmesh/operators/bmo_mirror.c         |  2 ++
 source/blender/bmesh/operators/bmo_primitive.c      |  2 ++
 source/blender/bmesh/operators/bmo_removedoubles.c  |  2 ++
 .../blender/bmesh/operators/bmo_smooth_laplacian.c  |  2 ++
 source/blender/bmesh/operators/bmo_subdivide.c      |  2 ++
 source/blender/bmesh/operators/bmo_symmetrize.c     |  7 +++++++
 source/blender/bmesh/operators/bmo_triangulate.c    |  2 ++
 source/blender/bmesh/operators/bmo_unsubdivide.c    |  3 +++
 source/blender/bmesh/operators/bmo_wireframe.c      |  2 ++
 21 files changed, 71 insertions(+), 9 deletions(-)

diff --git a/source/blender/bmesh/operators/bmo_beautify.c b/source/blender/bmesh/operators/bmo_beautify.c
index adf8ed4df67..ed393a4affa 100644
--- a/source/blender/bmesh/operators/bmo_beautify.c
+++ b/source/blender/bmesh/operators/bmo_beautify.c
@@ -22,6 +22,19 @@
 
 /** \file blender/bmesh/operators/bmo_beautify.c
  *  \ingroup bmesh
+ *
+ * Beautify the mesh by rotating edes between triangles
+ * to more attractive positions until no more rotations can be made.
+ *
+ * In princible this is very simple however there is the possability of
+ * going into an eternal loop where edges keep rotating.
+ * To avoid this - each edge stores a hash of it previous
+ * states so as not to rotate back.
+ *
+ * TODO
+ * - Take face normals into account.
+ * - Use a stack of rotations to perform the best onces first
+ *   similar to edge-collapse-decimate.
  */
 
 #include "BLI_math.h"
diff --git a/source/blender/bmesh/operators/bmo_bevel.c b/source/blender/bmesh/operators/bmo_bevel.c
index 052ae9336ab..dc06b0b4f13 100644
--- a/source/blender/bmesh/operators/bmo_bevel.c
+++ b/source/blender/bmesh/operators/bmo_bevel.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_bevel.c
  *  \ingroup bmesh
+ *
+ * Bevel wrapper around #BM_mesh_bevel
  */
 
 #include "BLI_utildefines.h"
diff --git a/source/blender/bmesh/operators/bmo_connect.c b/source/blender/bmesh/operators/bmo_connect.c
index dc00d020083..2e9cb11569d 100644
--- a/source/blender/bmesh/operators/bmo_connect.c
+++ b/source/blender/bmesh/operators/bmo_connect.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_connect.c
  *  \ingroup bmesh
+ *
+ * Connect verts across faces (splits faces) and bridge tool.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_create.c b/source/blender/bmesh/operators/bmo_create.c
index b8b78aab277..ad858c514d2 100644
--- a/source/blender/bmesh/operators/bmo_create.c
+++ b/source/blender/bmesh/operators/bmo_create.c
@@ -15,13 +15,15 @@
  * along with this program; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  *
- * Contributor(s): Joseph Eagar.
+ * Contributor(s): Joseph Eagar, Campbell Barton.
  *
  * ***** END GPL LICENSE BLOCK *****
  */
 
 /** \file blender/bmesh/operators/bmo_create.c
- *  \ingroup bmesh
+ *  \ingroup bmesh 
+ *
+ * Create faces or edges (Fkey by default).
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_dissolve.c b/source/blender/bmesh/operators/bmo_dissolve.c
index 4a241ca645f..13d706d8eed 100644
--- a/source/blender/bmesh/operators/bmo_dissolve.c
+++ b/source/blender/bmesh/operators/bmo_dissolve.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_dissolve.c
  *  \ingroup bmesh
+ *
+ * Removes isolated geometry regions without creating holes in the mesh.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_dupe.c b/source/blender/bmesh/operators/bmo_dupe.c
index 1448129ccde..9cc96fdca5a 100644
--- a/source/blender/bmesh/operators/bmo_dupe.c
+++ b/source/blender/bmesh/operators/bmo_dupe.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_dupe.c
  *  \ingroup bmesh
+ *
+ * Duplicate, Split, Spint operators.
  */
 
 #include "MEM_guardedalloc.h"
@@ -124,7 +126,6 @@ static BMEdge *copy_edge(BMOperator *op,
  *
  * Copy an existing face from one bmesh to another.
  */
-
 static BMFace *copy_face(BMOperator *op,
                          BMOpSlot *slot_facemap_out,
                          BMesh *source_mesh,
@@ -183,7 +184,6 @@ static BMFace *copy_face(BMOperator *op,
  *
  * Internal Copy function.
  */
-
 static void bmo_mesh_copy(BMOperator *op, BMesh *bm_src, BMesh *bm_dst)
 {
 
@@ -320,7 +320,6 @@ static void bmo_mesh_copy(BMOperator *op, BMesh *bm_src, BMesh *bm_dst)
  * BMOP_DUPE_ENEW: Buffer containing pointers to the new mesh edges
  * BMOP_DUPE_FNEW: Buffer containing pointers to the new mesh faces
  */
-
 void bmo_duplicate_exec(BMesh *bm, BMOperator *op)
 {
 	BMOperator *dupeop = op;
@@ -378,11 +377,10 @@ void BMO_dupe_from_flag(BMesh *bm, int htype, const char hflag)
  * BMOP_DUPE_EOUTPUT: Buffer containing pointers to the split mesh edges
  * BMOP_DUPE_FOUTPUT: Buffer containing pointers to the split mesh faces
  */
-
-#define SPLIT_INPUT 1
-
 void bmo_split_exec(BMesh *bm, BMOperator *op)
 {
+#define SPLIT_INPUT 1
+
 	BMOperator *splitop = op;
 	BMOperator dupeop;
 	BMOperator delop;
@@ -455,6 +453,8 @@ void bmo_split_exec(BMesh *bm, BMOperator *op)
 	/* cleanup */
 	BMO_op_finish(bm, &delop);
 	BMO_op_finish(bm, &dupeop);
+
+#undef SPLIT_INPUT
 }
 
 
@@ -478,7 +478,6 @@ void bmo_delete_exec(BMesh *bm, BMOperator *op)
  * Extrude or duplicate geometry a number of times,
  * rotating and possibly translating after each step
  */
-
 void bmo_spin_exec(BMesh *bm, BMOperator *op)
 {
 	BMOperator dupop, extop;
diff --git a/source/blender/bmesh/operators/bmo_edgeloop_fill.c b/source/blender/bmesh/operators/bmo_edgeloop_fill.c
index cf4303103ec..604feeeef5d 100644
--- a/source/blender/bmesh/operators/bmo_edgeloop_fill.c
+++ b/source/blender/bmesh/operators/bmo_edgeloop_fill.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_edgeloop_fill.c
  *  \ingroup bmesh
+ *
+ * Fill discreet edge loop(s) with faces.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_edgenet.c b/source/blender/bmesh/operators/bmo_edgenet.c
index cf91dfd0f15..124579c837e 100644
--- a/source/blender/bmesh/operators/bmo_edgenet.c
+++ b/source/blender/bmesh/operators/bmo_edgenet.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_edgenet.c
  *  \ingroup bmesh
+ *
+ * Edge-Net for filling in open edge-loops.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_extrude.c b/source/blender/bmesh/operators/bmo_extrude.c
index 62220510623..acb1001ca83 100644
--- a/source/blender/bmesh/operators/bmo_extrude.c
+++ b/source/blender/bmesh/operators/bmo_extrude.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_extrude.c
  *  \ingroup bmesh
+ *
+ * Extrude faces and solidify.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_hull.c b/source/blender/bmesh/operators/bmo_hull.c
index 810b608b28e..500e984f4c9 100644
--- a/source/blender/bmesh/operators/bmo_hull.c
+++ b/source/blender/bmesh/operators/bmo_hull.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_hull.c
  *  \ingroup bmesh
+ *
+ * Create a convex hull using bullet physics library.
  */
 
 #ifdef WITH_BULLET
diff --git a/source/blender/bmesh/operators/bmo_inset.c b/source/blender/bmesh/operators/bmo_inset.c
index ef99dae5ac9..a3656ce5b74 100644
--- a/source/blender/bmesh/operators/bmo_inset.c
+++ b/source/blender/bmesh/operators/bmo_inset.c
@@ -22,6 +22,11 @@
 
 /** \file blender/bmesh/operators/bmo_inset.c
  *  \ingroup bmesh
+ *
+ * Inset face regions.
+ *
+ * TODO
+ * - Inset indervidual faces.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_join_triangles.c b/source/blender/bmesh/operators/bmo_join_triangles.c
index e052968a6a0..5e4fa29d953 100644
--- a/source/blender/bmesh/operators/bmo_join_triangles.c
+++ b/source/blender/bmesh/operators/bmo_join_triangles.c
@@ -22,6 +22,11 @@
 
 /** \file blender/bmesh/operators/bmo_join_triangles.c
  *  \ingroup bmesh
+ *
+ * Convert triangle to quads.
+ *
+ * TODO
+ * - convert triangles to any sided faces, not just quads.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_mirror.c b/source/blender/bmesh/operators/bmo_mirror.c
index 48b2f76665c..6aff41b47d1 100644
--- a/source/blender/bmesh/operators/bmo_mirror.c
+++ b/source/blender/bmesh/operators/bmo_mirror.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_mirror.c
  *  \ingroup bmesh
+ *
+ * Basic mirror, optionally with UVs's.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_primitive.c b/source/blender/bmesh/operators/bmo_primitive.c
index 10a48c1b78c..9f17c1dd8e3 100644
--- a/source/blender/bmesh/operators/bmo_primitive.c
+++ b/source/blender/bmesh/operators/bmo_primitive.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_primitive.c
  *  \ingroup bmesh
+ *
+ * Primitive shapes.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_removedoubles.c b/source/blender/bmesh/operators/bmo_removedoubles.c
index 65b3267914f..6d9ea173960 100644
--- a/source/blender/bmesh/operators/bmo_removedoubles.c
+++ b/source/blender/bmesh/operators/bmo_removedoubles.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_removedoubles.c
  *  \ingroup bmesh
+ *
+ * Welding and merging functionality.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_smooth_laplacian.c b/source/blender/bmesh/operators/bmo_smooth_laplacian.c
index 0c0a2c308ee..12368d1aeda 100644
--- a/source/blender/bmesh/operators/bmo_smooth_laplacian.c
+++ b/source/blender/bmesh/operators/bmo_smooth_laplacian.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_smooth_laplacian.c
  *  \ingroup bmesh
+ *
+ * Advanced smoothing.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_subdivide.c b/source/blender/bmesh/operators/bmo_subdivide.c
index 9115ee882dd..32c5385bee6 100644
--- a/source/blender/bmesh/operators/bmo_subdivide.c
+++ b/source/blender/bmesh/operators/bmo_subdivide.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_subdivide.c
  *  \ingroup bmesh
+ *
+ * Edge based subdivision with various subdivision patterns.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_symmetrize.c b/source/blender/bmesh/operators/bmo_symmetrize.c
index 0bfc81f83cf..b684240dc76 100644
--- a/source/blender/bmesh/operators/bmo_symmetrize.c
+++ b/source/blender/bmesh/operators/bmo_symmetrize.c
@@ -20,6 +20,13 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file blender/bmesh/operators/bmo_symmetrize.c
+ *  \ingroup bmesh
+ *
+ * Makes the mesh symmetrical by splitting along an axis and duplicating the geometry.
+ */
+
+
 #include "MEM_guardedalloc.h"
 
 #include "BLI_array.h"
diff --git a/source/blender/bmesh/operators/bmo_triangulate.c b/source/blender/bmesh/operators/bmo_triangulate.c
index 29c3764045e..754709b18c0 100644
--- a/source/blender/bmesh/operators/bmo_triangulate.c
+++ b/source/blender/bmesh/operators/bmo_triangulate.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_triangulate.c
  *  \ingroup bmesh
+ *
+ * Triangulate faces, also defines triangle fill.
  */
 
 #include "MEM_guardedalloc.h"
diff --git a/source/blender/bmesh/operators/bmo_unsubdivide.c b/source/blender/bmesh/operators/bmo_unsubdivide.c
index 784e695efb0..c1cfb1866f4 100644
--- a/source/blender/bmesh/operators/bmo_unsubdivide.c
+++ b/source/blender/bmesh/operators/bmo_unsubdivide.c
@@ -22,6 +22,9 @@
 
 /** \file blender/bmesh/operators/bmo_unsubdivide.c
  *  \ingroup bmesh
+ *
+ * Pattern based geometry reduction which has the result similar to undoing
+ * a subdivide operation.
  */
 
 #include "BLI_math.h"
diff --git a/source/blender/bmesh/operators/bmo_wireframe.c b/source/blender/bmesh/operators/bmo_wireframe.c
index 00838533104..935a743116e 100644
--- a/source/blender/bmesh/operators/bmo_wireframe.c
+++ b/source/blender/bmesh/operators/bmo_wireframe.c
@@ -22,6 +22,8 @@
 
 /** \file blender/bmesh/operators/bmo_wireframe.c
  *  \ingroup bmesh
+ *
+ * Creates a solid wireframe from conected faces.
  */
 
 #include "MEM_guardedalloc.h"