bmesh operator naming - use clearer names for args eg: (mat -> matrix, use_singleedge -> use_single_edge)

also remove duplicate docs for operator arg formatting.

4 files changed, 62 insertions, 89 deletions

diff --git a/source/blender/bmesh/intern/bmesh_opdefines.c b/source/blender/bmesh/intern/bmesh_opdefines.c
index 8e2a2b22508..502dafeb5c3 100644
--- a/source/blender/bmesh/intern/bmesh_opdefines.c
+++ b/source/blender/bmesh/intern/bmesh_opdefines.c
@@ -254,11 +254,11 @@ static BMOpDefine bmo_mirror_def = {
 	"mirror",
 	/* slots_in */
 	{{"geom", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT | BM_EDGE | BM_FACE}},     /* input geometry */
-	 {"mat",         BMO_OP_SLOT_MAT},      /* matrix defining the mirror transformation */
-	 {"merge_dist", BMO_OP_SLOT_FLT},       /* maximum distance for merging.  does no merging if 0. */
-	 {"axis",         BMO_OP_SLOT_INT},     /* the axis to use, 0, 1, or 2 for x, y, z */
-	 {"mirror_u",        BMO_OP_SLOT_BOOL}, /* mirror UVs across the u axis */
-	 {"mirror_v",        BMO_OP_SLOT_BOOL}, /* mirror UVs across the v axis */
+	 {"matrix",          BMO_OP_SLOT_MAT},   /* matrix defining the mirror transformation */
+	 {"merge_dist",      BMO_OP_SLOT_FLT},   /* maximum distance for merging.  does no merging if 0. */
+	 {"axis",            BMO_OP_SLOT_INT},   /* the axis to use, 0, 1, or 2 for x, y, z */
+	 {"mirror_u",        BMO_OP_SLOT_BOOL},  /* mirror UVs across the u axis */
+	 {"mirror_v",        BMO_OP_SLOT_BOOL},  /* mirror UVs across the v axis */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -587,9 +587,9 @@ static BMOpDefine bmo_edgenet_prepare_def = {
 static BMOpDefine bmo_rotate_def = {
 	"rotate",
 	/* slots_in */
-	{{"cent", BMO_OP_SLOT_VEC},  /* center of rotation */
-	 {"mat", BMO_OP_SLOT_MAT},   /* matrix defining rotation */
-	 {"verts", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT}},  /* input vertices */
+	{{"cent",            BMO_OP_SLOT_VEC},  /* center of rotation */
+	 {"matrix",          BMO_OP_SLOT_MAT},  /* matrix defining rotation */
+	 {"verts",           BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT}},  /* input vertices */
 	 {{'\0'}},
 	},
 	{{{'\0'}}},  /* no output */
@@ -642,8 +642,8 @@ static BMOpDefine bmo_scale_def = {
 static BMOpDefine bmo_transform_def = {
 	"transform",
 	/* slots_in */
-	{{"mat", BMO_OP_SLOT_MAT},  /* transform matrix */
-	 {"verts", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT}},  /* input vertices */
+	{{"matrix",          BMO_OP_SLOT_MAT},  /* transform matrix */
+	 {"verts",           BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT}},  /* input vertices */
 	 {{'\0'}},
 	},
 	{{{'\0'}}},  /* no output */
@@ -911,7 +911,7 @@ static BMOpDefine bmo_triangulate_def = {
 	/* slots_out */
 	{{"edges.out", BMO_OP_SLOT_ELEMENT_BUF, {BM_EDGE}},
 	 {"faces.out", BMO_OP_SLOT_ELEMENT_BUF, {BM_FACE}},
-	 {"facemap.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
+	 {"face_map.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
 	 {{'\0'}},
 	},
 	bmo_triangulate_exec,
@@ -950,13 +950,13 @@ static BMOpDefine bmo_subdivide_edges_def = {
 	 {"along_normal", BMO_OP_SLOT_FLT},
 	 {"cuts", BMO_OP_SLOT_INT},
 	 {"seed", BMO_OP_SLOT_INT},
-	 {"custompatterns", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_INTERNAL}},  /* uses custom pointers */
-	 {"edgepercents", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_FLOAT}},
+	 {"custom_patterns", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_INTERNAL}},  /* uses custom pointers */
+	 {"edge_percents", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_FLOAT}},
 
 	 {"quad_corner_type",  BMO_OP_SLOT_INT}, /* quad corner type, see bmesh_operators.h */
-	 {"use_gridfill", BMO_OP_SLOT_BOOL},   /* fill in fully-selected faces with a grid */
-	 {"use_singleedge", BMO_OP_SLOT_BOOL}, /* tessellate the case of one edge selected in a quad or triangle */
-	 {"use_onlyquads", BMO_OP_SLOT_BOOL},  /* only subdivide quads (for loopcut) */
+	 {"use_grid_fill", BMO_OP_SLOT_BOOL},   /* fill in fully-selected faces with a grid */
+	 {"use_single_edge", BMO_OP_SLOT_BOOL}, /* tessellate the case of one edge selected in a quad or triangle */
+	 {"use_only_quads", BMO_OP_SLOT_BOOL},  /* only subdivide quads (for loopcut) */
 	 {"use_sphere", BMO_OP_SLOT_BOOL},     /* for making new primitives only */
 	 {{'\0'}},
 	},
@@ -980,7 +980,7 @@ static BMOpDefine bmo_delete_def = {
 	"delete",
 	/* slots_in */
 	{{"geom", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT | BM_EDGE | BM_FACE}},
-	 {"context", BMO_OP_SLOT_INT},
+	 {"context", BMO_OP_SLOT_INT},  /* enum DEL_VERTS ... */
 	 {{'\0'}},
 	},
 	{{{'\0'}}},  /* no output */
@@ -1007,9 +1007,9 @@ static BMOpDefine bmo_duplicate_def = {
 	 {"geom.out", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT | BM_EDGE | BM_FACE}},
 	/* facemap maps from source faces to dupe
 	 * faces, and from dupe faces to source faces */
-	 {"facemap.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
-	 {"boundarymap.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
-	 {"isovertmap.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
+	 {"face_map.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
+	 {"boundary_map.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
+	 {"isovert_map.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
 	{{'\0'}},
 	},
 	bmo_duplicate_exec,
@@ -1033,8 +1033,8 @@ static BMOpDefine bmo_split_def = {
 	},
 	/* slots_out */
 	{{"geom.out", BMO_OP_SLOT_ELEMENT_BUF, {BM_VERT | BM_EDGE | BM_FACE}},
-	 {"boundarymap.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
-	 {"isovertmap.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
+	 {"boundary_map.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
+	 {"isovert_map.out", BMO_OP_SLOT_MAPPING, {BMO_OP_SLOT_SUBTYPE_MAP_ELEM}},
 	 {{'\0'}},
 	},
 	bmo_split_exec,
@@ -1252,10 +1252,10 @@ static BMOpDefine bmo_split_edges_def = {
 static BMOpDefine bmo_create_grid_def = {
 	"create_grid",
 	/* slots_in */
-	{{"x_segments",         BMO_OP_SLOT_INT}, /* number of x segments */
-	 {"y_segments",         BMO_OP_SLOT_INT}, /* number of y segments */
-	 {"size",         BMO_OP_SLOT_FLT},     /* size of the grid */
-	 {"mat",         BMO_OP_SLOT_MAT},      /* matrix to multiply the new geometry with */
+	{{"x_segments",      BMO_OP_SLOT_INT},  /* number of x segments */
+	 {"y_segments",      BMO_OP_SLOT_INT},  /* number of y segments */
+	 {"size",            BMO_OP_SLOT_FLT},  /* size of the grid */
+	 {"matrix",          BMO_OP_SLOT_MAT},  /* matrix to multiply the new geometry with */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -1274,10 +1274,10 @@ static BMOpDefine bmo_create_grid_def = {
 static BMOpDefine bmo_create_uvsphere_def = {
 	"create_uvsphere",
 	/* slots_in */
-	{{"u_segments",         BMO_OP_SLOT_INT}, /* number of u segments */
-	 {"v_segments",         BMO_OP_SLOT_INT}, /* number of v segment */
-	 {"diameter",         BMO_OP_SLOT_FLT}, /* diameter */
-	 {"mat",         BMO_OP_SLOT_MAT}, /* matrix to multiply the new geometry with */
+	{{"u_segments",      BMO_OP_SLOT_INT}, /* number of u segments */
+	 {"v_segments",      BMO_OP_SLOT_INT}, /* number of v segment */
+	 {"diameter",        BMO_OP_SLOT_FLT}, /* diameter */
+	 {"matrix",          BMO_OP_SLOT_MAT}, /* matrix to multiply the new geometry with */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -1296,9 +1296,9 @@ static BMOpDefine bmo_create_uvsphere_def = {
 static BMOpDefine bmo_create_icosphere_def = {
 	"create_icosphere",
 	/* slots_in */
-	{{"subdivisions",         BMO_OP_SLOT_INT}, /* how many times to recursively subdivide the sphere */
-	 {"diameter",         BMO_OP_SLOT_FLT}, /* diameter */
-	 {"mat",         BMO_OP_SLOT_MAT}, /* matrix to multiply the new geometry with */
+	{{"subdivisions",    BMO_OP_SLOT_INT}, /* how many times to recursively subdivide the sphere */
+	 {"diameter",        BMO_OP_SLOT_FLT}, /* diameter */
+	 {"matrix",          BMO_OP_SLOT_MAT}, /* matrix to multiply the new geometry with */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -1317,7 +1317,7 @@ static BMOpDefine bmo_create_icosphere_def = {
 static BMOpDefine bmo_create_monkey_def = {
 	"create_monkey",
 	/* slots_in */
-	{{"mat", BMO_OP_SLOT_MAT}, /* matrix to multiply the new geometry with */
+	{{"matrix", BMO_OP_SLOT_MAT}, /* matrix to multiply the new geometry with */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -1336,13 +1336,13 @@ static BMOpDefine bmo_create_monkey_def = {
 static BMOpDefine bmo_create_cone_def = {
 	"create_cone",
 	/* slots_in */
-	{{"cap_ends", BMO_OP_SLOT_BOOL},        /* whether or not to fill in the ends with faces */
-	 {"cap_tris", BMO_OP_SLOT_BOOL},        /* fill ends with triangles instead of ngons */
-	 {"segments", BMO_OP_SLOT_INT},
-	 {"diameter1", BMO_OP_SLOT_FLT},        /* diameter of one end */
-	 {"diameter2", BMO_OP_SLOT_FLT},        /* diameter of the opposite */
-	 {"depth", BMO_OP_SLOT_FLT},            /* distance between ends */
-	 {"mat", BMO_OP_SLOT_MAT},              /* matrix to multiply the new geometry with */
+	{{"cap_ends",        BMO_OP_SLOT_BOOL},  /* whether or not to fill in the ends with faces */
+	 {"cap_tris",        BMO_OP_SLOT_BOOL},  /* fill ends with triangles instead of ngons */
+	 {"segments",        BMO_OP_SLOT_INT},
+	 {"diameter1",       BMO_OP_SLOT_FLT},  /* diameter of one end */
+	 {"diameter2",       BMO_OP_SLOT_FLT},  /* diameter of the opposite */
+	 {"depth",           BMO_OP_SLOT_FLT},  /* distance between ends */
+	 {"matrix",          BMO_OP_SLOT_MAT},  /* matrix to multiply the new geometry with */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -1359,11 +1359,11 @@ static BMOpDefine bmo_create_cone_def = {
 static BMOpDefine bmo_create_circle_def = {
 	"create_circle",
 	/* slots_in */
-	{{"cap_ends", BMO_OP_SLOT_BOOL},        /* whether or not to fill in the ends with faces */
-	 {"cap_tris", BMO_OP_SLOT_BOOL},        /* fill ends with triangles instead of ngons */
-	 {"segments", BMO_OP_SLOT_INT},
-	 {"diameter", BMO_OP_SLOT_FLT},         /* diameter of one end */
-	 {"mat", BMO_OP_SLOT_MAT},              /* matrix to multiply the new geometry with */
+	{{"cap_ends",        BMO_OP_SLOT_BOOL},  /* whether or not to fill in the ends with faces */
+	 {"cap_tris",        BMO_OP_SLOT_BOOL},  /* fill ends with triangles instead of ngons */
+	 {"segments",        BMO_OP_SLOT_INT},
+	 {"diameter",        BMO_OP_SLOT_FLT},  /* diameter of one end */
+	 {"matrix",          BMO_OP_SLOT_MAT},  /* matrix to multiply the new geometry with */
 	 {{'\0'}},
 	},
 	/* slots_out */
@@ -1382,8 +1382,8 @@ static BMOpDefine bmo_create_circle_def = {
 static BMOpDefine bmo_create_cube_def = {
 	"create_cube",
 	/* slots_in */
-	{{"size", BMO_OP_SLOT_FLT},             /* size of the cube */
-	 {"mat", BMO_OP_SLOT_MAT},              /* matrix to multiply the new geometry with */
+	{{"size",            BMO_OP_SLOT_FLT},  /* size of the cube */
+	 {"matrix",          BMO_OP_SLOT_MAT},  /* matrix to multiply the new geometry with */
 	 {{'\0'}},
 	},
 	/* slots_out */
diff --git a/source/blender/bmesh/intern/bmesh_operator_api.h b/source/blender/bmesh/intern/bmesh_operator_api.h
index bebd3215d93..df67f459a34 100644
--- a/source/blender/bmesh/intern/bmesh_operator_api.h
+++ b/source/blender/bmesh/intern/bmesh_operator_api.h
@@ -240,43 +240,6 @@ int BMO_mesh_enabled_flag_count(BMesh *bm, const char htype, const short oflag);
 int BMO_mesh_disabled_flag_count(BMesh *bm, const char htype, const short oflag);
 
 /*---------formatted operator initialization/execution-----------*/
-/*
- * this system is used to execute or initialize an operator,
- * using a formatted-string system.
- *
- * for example, BMO_op_callf(bm, BMO_FLAG_DEFAULTS, "delete geom=%hf context=%i", BM_ELEM_SELECT, DEL_FACES);
- * . . .will execute the delete operator, feeding in selected faces, deleting them.
- *
- * the basic format for the format string is:
- *   [operatorname] [slot_name]=%[code] [slot_name]=%[code]
- *
- * as in printf, you pass in one additional argument to the function
- * for every code.
- *
- * the formatting codes are:
- *    %d - put int in slot
- *    %f - put float in slot
- *    %p - put pointer in slot
- *    %h[f/e/v] - put elements with a header flag in slot.
- *                 the letters after %h define which element types to use,
- *             so e.g. %hf will do faces, %hfe will do faces and edges,
- *             %hv will do verts, etc.  must pass in at least one
- *             element type letter.
- *    %H[f/e/v] - same as %h, but tests if the flag is disabled
- *    %f[f/e/v] - same as %h, except it deals with tool flags instead of
- *                 header flags.
- *    %F[f/e/v] - same as %f, but tests if the flag is disabled
- *    %a[f/e/v] - pass all elements (of types specified by f/e/v) to the
- *                 slot.
- *    %e        - pass in a single element.
- *    %v - pointer to a float vector of length 3.
- *    %m[3/4] - matrix, 3/4 refers to the matrix size, 3 or 4.  the
- *              corresponding argument must be a pointer to
- *          a float matrix.
- *    %s - copy a slot from another op, instead of mapping to one
- *         argument, it maps to two, a pointer to an operator and
- *     a slot name.
- */
 void BMO_push(BMesh *bm, BMOperator *op);
 void BMO_pop(BMesh *bm);
 
@@ -443,15 +406,18 @@ void *BMO_slot_buffer_alloc(BMOperator *op, BMOpSlot slot_args[BMO_OP_MAX_SLOTS]
 void BMO_slot_buffer_from_all(BMesh *bm, BMOperator *op, BMOpSlot slot_args[BMO_OP_MAX_SLOTS],
                               const char *slot_name, const char htype);
 
-/* this part of the API is used to iterate over element buffer or
+/**
+ * This part of the API is used to iterate over element buffer or
  * mapping slots.
  *
  * for example, iterating over the faces in a slot is:
  *
+ * \code{.c}
+ *
  *    BMOIter oiter;
  *    BMFace *f;
  *
- *    f = BMO_iter_new(&oiter, bm, some_operator, "slot_name", BM_FACE);
+ *    f = BMO_iter_new(&oiter, some_operator, "slot_name", BM_FACE);
  *    for (; f; f = BMO_iter_step(&oiter)) {
  *        /do something with the face
  *    }
@@ -472,6 +438,7 @@ void BMO_slot_buffer_from_all(BMesh *bm, BMOperator *op, BMOpSlot slot_args[BMO_
  *        //  *((void**)BMO_iter_map_value(&oiter));
  *        //or something like that.
  *    }
+ * \endcode
  */
 
 /* contents of this structure are private,
diff --git a/source/blender/bmesh/intern/bmesh_operators.c b/source/blender/bmesh/intern/bmesh_operators.c
index 18caefc13c3..ba38f230f0b 100644
--- a/source/blender/bmesh/intern/bmesh_operators.c
+++ b/source/blender/bmesh/intern/bmesh_operators.c
@@ -1485,6 +1485,12 @@ static int bmo_opname_to_opcode(const char *opname)
 /**
  * \brief Format Strings for #BMOperator Initialization.
  *
+ * This system is used to execute or initialize an operator,
+ * using a formatted-string system.
+ *
+ * The basic format for the format string is:
+ * `[operatorname] [slot_name]=%[code] [slot_name]=%[code]`
+ *
  * Example:
  *
  * \code{.c}
diff --git a/source/blender/bmesh/intern/bmesh_operators.h b/source/blender/bmesh/intern/bmesh_operators.h
index 9a89e2bc996..d02b0dce728 100644
--- a/source/blender/bmesh/intern/bmesh_operators.h
+++ b/source/blender/bmesh/intern/bmesh_operators.h
@@ -97,8 +97,8 @@ void BM_mesh_esubdivide(BMesh *bm, const char edge_hflag,
                         float smooth, float fractal, float along_normal,
                         int numcuts,
                         int seltype, int cornertype,
-                        const short use_singleedge, const short use_gridfill,
-                        const short use_onlyquads,
+                        const short use_single_edge, const short use_grid_fill,
+                        const short use_only_quads,
                         int seed);
 
 #include "intern/bmesh_operator_api_inline.h"