[Bf-blender-cvs] [d3bf4929de0] master: Cleanup: update mball.c comments

[Campbell Barton]

Commit: d3bf4929de0a908760bf2d3fdac336cacd08c5bd
Author: Campbell Barton
Date:   Wed Aug 19 14:15:10 2020 +1000
Branches: master
https://developer.blender.org/rBd3bf4929de0a908760bf2d3fdac336cacd08c5bd

Cleanup: update mball.c comments

Some errors in comments, references to old function names.

===================================================================

M	source/blender/blenkernel/intern/mball.c

===================================================================

diff --git a/source/blender/blenkernel/intern/mball.c b/source/blender/blenkernel/intern/mball.c
index de07c96e3f0..d2f7ee68430 100644
--- a/source/blender/blenkernel/intern/mball.c
+++ b/source/blender/blenkernel/intern/mball.c
@@ -196,11 +196,11 @@ MetaElem *BKE_mball_element_add(MetaBall *mb, const int type)
   return ml;
 }
 /**
- * Compute bounding box of all MetaElems/MetaBalls.
+ * Compute bounding box of all #MetaElem / #MetaBall
  *
- * Bounding box is computed from polygonized surface. Object *ob is
- * basic MetaBall (usually with name Meta). All other MetaBalls (with
- * names Meta.001, Meta.002, etc) are included in this Bounding Box.
+ * Bounding box is computed from polygonized surface. \a ob is
+ * basic meta-balls (with name `Meta` for example). All other meta-ball objects
+ * (with names `Meta.001`, `Meta.002`, etc) are included in this bounding-box.
  */
 void BKE_mball_texspace_calc(Object *ob)
 {
@@ -298,25 +298,30 @@ float *BKE_mball_make_orco(Object *ob, ListBase *dispbase)
   return orcodata;
 }
 
-/* Note on mball basis stuff 2.5x (this is a can of worms)
+/**
+ * \brief Test, if \a ob is a basis meta-ball.
+ *
+ * It test last character of Object ID name. If last character
+ * is digit it return 0, else it return 1.
+ *
+ *
+ * Meta-Ball Basis Notes from Blender-2.5x
+ * =======================================
+ *
+ * This is a can of worms.
+ *
  * This really needs a rewrite/refactor its totally broken in anything other then basic cases
- * Multiple Scenes + Set Scenes & mixing mball basis SHOULD work but fails to update the depsgraph
- * on rename and linking into scenes or removal of basis mball.
+ * Multiple Scenes + Set Scenes & mixing meta-ball basis _should_ work but fails to update the
+ * depsgraph on rename and linking into scenes or removal of basis meta-ball.
  * So take care when changing this code.
  *
- * Main idiot thing here is that the system returns find_basis_mball()
- * objects which fail a is_basis_mball() test.
+ * Main idiot thing here is that the system returns #BKE_mball_basis_find()
+ * objects which fail a #BKE_mball_is_basis() test.
  *
- * Not only that but the depsgraph and their areas depend on this behavior!,
+ * Not only that but the depsgraph and their areas depend on this behavior,
  * so making small fixes here isn't worth it.
  * - Campbell
  */
-
-/** \brief Test, if Object *ob is basic MetaBall.
- *
- * It test last character of Object ID name. If last character
- * is digit it return 0, else it return 1.
- */
 bool BKE_mball_is_basis(Object *ob)
 {
   /* just a quick test */
@@ -378,12 +383,12 @@ bool BKE_mball_is_any_unselected(const MetaBall *mb)
 }
 
 /**
- * \brief copy some properties from object to other metaball object with same base name
+ * \brief copy some properties from object to other meta-ball object with same base name
  *
- * When some properties (wiresize, threshold, update flags) of metaball are changed, then this
- * properties are copied to all metaballs in same "group" (metaballs with same base name: MBall,
- * MBall.001, MBall.002, etc). The most important is to copy properties to the base metaball,
- * because this metaball influence polygonization of metaballs. */
+ * When some properties (wire-size, threshold, update flags) of meta-ball are changed, then this
+ * properties are copied to all meta-balls in same "group" (meta-balls with same base name:
+ * `MBall`, `MBall.001`, `MBall.002`, etc). The most important is to copy properties to the base
+ * meta-ball, because this meta-ball influence polygonization of meta-balls. */
 void BKE_mball_properties_copy(Scene *scene, Object *active_object)
 {
   Scene *sce_iter = scene;
@@ -397,7 +402,7 @@ void BKE_mball_properties_copy(Scene *scene, Object *active_object)
   BLI_split_name_num(basisname, &basisnr, active_object->id.name + 2, '.');
 
   /* Pass depsgraph as NULL, which means we will not expand into
-   * duplis unlike when we generate the mball. Expanding duplis
+   * duplis unlike when we generate the meta-ball. Expanding duplis
    * would not be compatible when editing multiple view layers. */
   BKE_scene_base_iter_next(NULL, &iter, &sce_iter, 0, NULL, NULL);
   while (BKE_scene_base_iter_next(NULL, &iter, &sce_iter, 1, &base, &ob)) {
@@ -424,12 +429,11 @@ void BKE_mball_properties_copy(Scene *scene, Object *active_object)
 
 /** \brief This function finds basic MetaBall.
  *
- * Basic MetaBall doesn't include any number at the end of
- * its name. All MetaBalls with same base of name can be
- * blended. MetaBalls with different basic name can't be
- * blended.
+ * Basic meta-ball doesn't include any number at the end of
+ * its name. All meta-balls with same base of name can be
+ * blended. meta-balls with different basic name can't be blended.
  *
- * warning!, is_basis_mball() can fail on returned object, see long note above.
+ * \warning #BKE_mball_is_basis() can fail on returned object, see function docs for details.
  */
 Object *BKE_mball_basis_find(Scene *scene, Object *basis)
 {