[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [52593] trunk/blender/source/blender: code cleanup: bmesh operator comments, readying for doc-generation.

Campbell Barton ideasman42 at gmail.com
Tue Nov 27 07:53:29 CET 2012


Revision: 52593
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=52593
Author:   campbellbarton
Date:     2012-11-27 06:53:26 +0000 (Tue, 27 Nov 2012)
Log Message:
-----------
code cleanup: bmesh operator comments, readying for doc-generation.

Modified Paths:
--------------
    trunk/blender/source/blender/bmesh/intern/bmesh_opdefines.c
    trunk/blender/source/blender/bmesh/operators/bmo_connect.c
    trunk/blender/source/blender/editors/interface/interface_templates.c

Modified: trunk/blender/source/blender/bmesh/intern/bmesh_opdefines.c
===================================================================
--- trunk/blender/source/blender/bmesh/intern/bmesh_opdefines.c	2012-11-27 02:34:40 UTC (rev 52592)
+++ trunk/blender/source/blender/bmesh/intern/bmesh_opdefines.c	2012-11-27 06:53:26 UTC (rev 52593)
@@ -59,8 +59,10 @@
 #include "bmesh.h"
 #include "intern/bmesh_private.h"
 
-/* ok, I'm going to write a little docgen script. so all
- * bmop comments must conform to the following template/rules:
+/* The formatting of these bmesh operators is parsed by
+ * 'doc/python_api/rst_from_bmesh_opdefines.py'
+ * for use in python docs, so reStructuredText may be used
+ * rather then doxygen syntax.
  *
  * template (py quotes used because nested comments don't work
  * on all C compilers):
@@ -79,21 +81,22 @@
  * so the first line is the "title" of the bmop.
  * subsequent line blocks separated by blank lines
  * are paragraphs.  individual descriptions of slots
- * would be extracted from comments
- * next to them, e.g.
+ * are extracted from comments next to them.
  *
- * {BMO_OP_SLOT_ELEMENT_BUF, "geom.out"}, //output slot, boundary region
+ * eg:
+ *     {BMO_OP_SLOT_ELEMENT_BUF, "geom.out"},  """ output slot, boundary region """
  *
- * the doc generator would automatically detect the presence of "output slot"
- * and flag the slot as an output.  the same happens for "input slot".  also
- * note that "edges", "faces", "verts", "loops", and "geometry" are valid
- * substitutions for "slot".
+ * ... or:
  *
- * note that slots default to being input slots.
+ * """ output slot, boundary region """
+ *     {BMO_OP_SLOT_ELEMENT_BUF, "geom.out"},
+ *
+ * Both are acceptable.
+ * note that '//' comments are ignored.
  */
 
 /*
- * Vertex Smooth
+ * Vertex Smooth.
  *
  * Smooths vertices by using a basic vertex averaging scheme.
  */
@@ -104,7 +107,7 @@
 	 {"mirror_clip_x", BMO_OP_SLOT_BOOL},   /* set vertices close to the x axis before the operation to 0 */
 	 {"mirror_clip_y", BMO_OP_SLOT_BOOL},   /* set vertices close to the y axis before the operation to 0 */
 	 {"mirror_clip_z", BMO_OP_SLOT_BOOL},   /* set vertices close to the z axis before the operation to 0 */
-	 {"clip_dist",  BMO_OP_SLOT_FLT},       /* clipping threshod for the above three slots */
+	 {"clip_dist",  BMO_OP_SLOT_FLT},       /* clipping threshold for the above three slots */
 	 {"use_axis_x", BMO_OP_SLOT_BOOL},      /* smooth vertices along X axis */
 	 {"use_axis_y", BMO_OP_SLOT_BOOL},      /* smooth vertices along Y axis */
 	 {"use_axis_z", BMO_OP_SLOT_BOOL},      /* smooth vertices along Z axis */
@@ -116,9 +119,10 @@
 };
 
 /*
- * Vertext Smooth Laplacian
+ * Vertext Smooth Laplacian.
+ *
  * Smooths vertices by using Laplacian smoothing propose by.
- * Desbrun, et al. Implicit Fairing of Irregular Meshes using Diffusion and Curvature Flow
+ * Desbrun, et al. Implicit Fairing of Irregular Meshes using Diffusion and Curvature Flow.
  */
 static BMOpDefine bmo_smooth_laplacian_vert_def = {
 	"smooth_laplacian_vert",
@@ -138,16 +142,15 @@
 };
 
 /*
- * Right-Hand Faces
+ * Right-Hand Faces.
  *
  * Computes an "outside" normal for the specified input faces.
  */
-
 static BMOpDefine bmo_recalc_face_normals_def = {
 	"recalc_face_normals",
 	/* slots_in */
 	{{"faces", BMO_OP_SLOT_ELEMENT_BUF, {BM_FACE}},
-	 {"use_flip", BMO_OP_SLOT_BOOL},        /* internal flag, used by bmesh_rationalize_normals */
+	 {"use_flip", BMO_OP_SLOT_BOOL},  /* Reverse the result */
 	 {{'\0'}},
 	},
 	{{{'\0'}}},  /* no output */
@@ -156,13 +159,13 @@
 };
 
 /*
- * Region Extend
+ * Region Extend.
  *
  * used to implement the select more/less tools.
  * this puts some geometry surrounding regions of
  * geometry in geom into geom.out.
  *
- * if usefaces is 0 then geom.out spits out verts and edges,
+ * if use_faces is 0 then geom.out spits out verts and edges,
  * otherwise it spits out faces.
  */
 static BMOpDefine bmo_region_extend_def = {
@@ -182,16 +185,16 @@
 };
 
 /*
- * Edge Rotate
+ * Edge Rotate.
  *
  * Rotates edges topologically.  Also known as "spin edge" to some people.
- * Simple example: [/] becomes [|] then [\].
+ * Simple example: ``[/] becomes [|] then [\]``.
  */
 static BMOpDefine bmo_rotate_edges_def = {
 	"rotate_edges",
 	/* slots_in */
 	{{"edges", BMO_OP_SLOT_ELEMENT_BUF, {BM_EDGE}},    /* input edges */
-	 {"use_ccw", BMO_OP_SLOT_BOOL},         /* rotate edge counter-clockwise if true, othewise clockwise */
+	 {"use_ccw", BMO_OP_SLOT_BOOL},         /* rotate edge counter-clockwise if true, otherwise clockwise */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -203,10 +206,10 @@
 };
 
 /*
- * Reverse Faces
+ * Reverse Faces.
  *
- * Reverses the winding (vertex order) of faces.  This has the effect of
- * flipping the normal.
+ * Reverses the winding (vertex order) of faces.
+ * This has the effect of flipping the normal.
  */
 static BMOpDefine bmo_reverse_faces_def = {
 	"reverse_faces",
@@ -220,7 +223,7 @@
 };
 
 /*
- * Edge Bisect
+ * Edge Bisect.
  *
  * Splits input edges (but doesn't do anything else).
  * This creates a 2-valence vert.
@@ -241,13 +244,12 @@
 };
 
 /*
- * Mirror
+ * Mirror.
  *
  * Mirrors geometry along an axis.  The resulting geometry is welded on using
  * merge_dist.  Pairs of original/mirrored vertices are welded using the merge_dist
  * parameter (which defines the minimum distance for welding to happen).
  */
-
 static BMOpDefine bmo_mirror_def = {
 	"mirror",
 	/* slots_in */
@@ -268,10 +270,10 @@
 };
 
 /*
- * Find Doubles
+ * Find Doubles.
  *
- * Takes input verts and find vertices they should weld to.  Outputs a
- * mapping slot suitable for use with the weld verts bmop.
+ * Takes input verts and find vertices they should weld to.
+ * Outputs a mapping slot suitable for use with the weld verts bmop.
  *
  * If keep_verts is used, vertices outside that set can only be merged
  * with vertices in that set.
@@ -293,7 +295,7 @@
 };
 
 /*
- * Remove Doubles
+ * Remove Doubles.
  *
  * Finds groups of vertices closer then dist and merges them together,
  * using the weld verts bmop.
@@ -311,11 +313,11 @@
 };
 
 /*
- * Auto Merge
+ * Auto Merge.
  *
- * Finds groups of vertices closer then dist and merges them together,
+ * Finds groups of vertices closer then **dist** and merges them together,
  * using the weld verts bmop.  The merges must go from a vert not in
- * verts to one in verts.
+ * **verts** to one in **verts**.
  */
 static BMOpDefine bmo_automerge_def = {
 	"automerge",
@@ -330,7 +332,7 @@
 };
 
 /*
- * Collapse Connected
+ * Collapse Connected.
  *
  * Collapses connected vertices
  */
@@ -345,9 +347,8 @@
 	BMO_OP_FLAG_UNTAN_MULTIRES,
 };
 
-
 /*
- * Facedata point Merge
+ * Face-Data Point Merge.
  *
  * Merge uv/vcols at a specific vertex.
  */
@@ -364,7 +365,7 @@
 };
 
 /*
- * Average Vertices Facevert Data
+ * Average Vertices Facevert Data.
  *
  * Merge uv/vcols associated with the input vertices at
  * the bounding box center. (I know, it's not averaging but
@@ -382,7 +383,7 @@
 };
 
 /*
- * Point Merge
+ * Point Merge.
  *
  * Merge verts together at a point.
  */
@@ -399,7 +400,7 @@
 };
 
 /*
- * Collapse Connected UVs
+ * Collapse Connected UV's.
  *
  * Collapses connected UV vertices.
  */
@@ -415,9 +416,9 @@
 };
 
 /*
- * Weld Verts
+ * Weld Verts.
  *
- * Welds verts together (kindof like remove doubles, merge, etc, all of which
+ * Welds verts together (kind-of like remove doubles, merge, etc, all of which
  * use or will use this bmop).  You pass in mappings from vertices to the vertices
  * they weld with.
  */
@@ -434,7 +435,7 @@
 };
 
 /*
- * Make Vertex
+ * Make Vertex.
  *
  * Creates a single vertex; this bmop was necessary
  * for click-create-vertex.
@@ -454,7 +455,7 @@
 };
 
 /*
- * Join Triangles
+ * Join Triangles.
  *
  * Tries to intelligently join triangles according
  * to various settings and stuff.
@@ -479,12 +480,11 @@
 };
 
 /*
- * Contextual Create
+ * Contextual Create.
  *
- * This is basically fkey, it creates
+ * This is basically F-key, it creates
  * new faces from vertices, makes stuff from edge nets,
- * makes wire edges, etc.  It also dissolves
- * faces.
+ * makes wire edges, etc.  It also dissolves faces.
  *
  * Three verts become a triangle, four become a quad.  Two
  * become a wire edge.
@@ -508,7 +508,7 @@
 };
 
 /*
- * Bridge edge loops with faces
+ * Bridge edge loops with faces.
  */
 static BMOpDefine bmo_bridge_loops_def = {
 	"bridge_loops",
@@ -526,6 +526,11 @@
 	0,
 };
 
+/*
+ * Edge Net Fill.
+ *
+ * Create faces defined by enclosed edges.
+ */
 static BMOpDefine bmo_edgenet_fill_def = {
 	"edgenet_fill",
 	/* slots_in */
@@ -550,7 +555,7 @@
 };
 
 /*
- * Edgenet Prepare
+ * Edgenet Prepare.
  *
  * Identifies several useful edge loop cases and modifies them so
  * they'll become a face when edgenet_fill is called.  The cases covered are:
@@ -574,7 +579,7 @@
 };
 
 /*
- * Rotate
+ * Rotate.
  *
  * Rotate vertices around a center, using a 3x3 rotation
  * matrix.  Equivalent of the old rotateflag function.
@@ -593,7 +598,7 @@
 };
 
 /*
- * Translate
+ * Translate.
  *
  * Translate vertices by an offset.  Equivalent of the
  * old translateflag function.
@@ -611,7 +616,7 @@
 };
 
 /*
- * Scale
+ * Scale.
  *
  * Scales vertices by an offset.
  */
@@ -629,7 +634,7 @@
 
 
 /*
- * Transform
+ * Transform.
  *
  * Transforms a set of vertices by a matrix.  Multiplies
  * the vertex coordinates with the matrix.
@@ -647,7 +652,7 @@
 };
 
 /*
- * Object Load BMesh
+ * Object Load BMesh.
  *
  * Loads a bmesh into an object/mesh.  This is a "private"
  * bmop.
@@ -666,7 +671,7 @@
 
 
 /*
- * BMesh to Mesh
+ * BMesh to Mesh.
  *
  * Converts a bmesh to a Mesh.  This is reserved for exiting editmode.
  */
@@ -687,7 +692,7 @@
 };
 
 /*
- * Mesh to BMesh
+ * Mesh to BMesh.
  *
  * Load the contents of a mesh into the bmesh.  this bmop is private, it's
  * reserved exclusively for entering editmode.
@@ -709,7 +714,7 @@
 };
 
 /*
- * Individual Face Extrude
+ * Individual Face Extrude.
  *
  * Extrudes faces individually.
  */
@@ -728,7 +733,7 @@
 };
 
 /*
- * Extrude Only Edges
+ * Extrude Only Edges.
  *
  * Extrudes Edges into faces, note that this is very simple, there's no fancy
  * winged extrusion.
@@ -748,7 +753,7 @@
 };
 
 /*
- * Individual Vertex Extrude
+ * Individual Vertex Extrude.
  *
  * Extrudes wire edges from vertices.
  */
@@ -767,6 +772,11 @@
 	0
 };
 
+/*
+ * Connect Verts.
+ *
+ * Split faces by adding edges that connect **verts**.
+ */
 static BMOpDefine bmo_connect_verts_def = {
 	"connect_verts",
 	/* slots_in */
@@ -781,6 +791,11 @@

@@ Diff output truncated at 10240 characters. @@



More information about the Bf-blender-cvs mailing list