Cleanup: correct/update comments

3 files changed, 13 insertions, 5 deletions

diff --git a/source/blender/editors/mesh/editmesh_tools.c b/source/blender/editors/mesh/editmesh_tools.c
index de37ddec885..231e6fbc2d9 100644
--- a/source/blender/editors/mesh/editmesh_tools.c
+++ b/source/blender/editors/mesh/editmesh_tools.c
@@ -3101,7 +3101,8 @@ static bool merge_firstlast(BMEditMesh *em,
    * so do extra check for data here
    */
 
-  /* do sanity check in mergemenu in edit.c ?*/
+  /* While #merge_type_itemf does a sanity check, this operation runs on all edit-mode objects.
+   * Some of them may not have the expected selection state. */
   if (use_first == false) {
     if (!em->bm->selected.last || ((BMEditSelection *)em->bm->selected.last)->htype != BM_VERT) {
       return false;
diff --git a/source/blender/editors/sculpt_paint/paint_vertex_color_utils.c b/source/blender/editors/sculpt_paint/paint_vertex_color_utils.c
index 7120f6a8748..dbc6044d2d8 100644
--- a/source/blender/editors/sculpt_paint/paint_vertex_color_utils.c
+++ b/source/blender/editors/sculpt_paint/paint_vertex_color_utils.c
@@ -610,7 +610,9 @@ BLI_INLINE uint mcol_alpha_sub(uint col_src, int fac)
   return col_mix;
 }
 
-/* wpaint has 'ED_wpaint_blend_tool' */
+/**
+ * \note weight-paint has an equivalent function: #ED_wpaint_blend_tool
+ */
 uint ED_vpaint_blend_tool(const int tool, const uint col, const uint paintcol, const int alpha_i)
 {
   switch ((IMB_BlendMode)tool) {
diff --git a/source/blender/editors/sculpt_paint/paint_vertex_weight_utils.c b/source/blender/editors/sculpt_paint/paint_vertex_weight_utils.c
index dc777572858..a65895a3405 100644
--- a/source/blender/editors/sculpt_paint/paint_vertex_weight_utils.c
+++ b/source/blender/editors/sculpt_paint/paint_vertex_weight_utils.c
@@ -273,10 +273,15 @@ BLI_INLINE float wval_exclusion(float weight, float paintval, float fac)
   return temp * fac + weight * mfac;
 }
 
-/* vpaint has 'vpaint_blend_tool' */
-/* result is not clamped from [0-1] */
+/**
+ * \param weight: Typically the current weight: #MDeformWeight.weight
+ *
+ * \return The final weight, not that this is _not_ clamped from [0-1].
+ * Clamping must be done on the final #MDeformWeight.weight
+ *
+ * \note vertex-paint has an equivalent function: #ED_vpaint_blend_tool
+ */
 float ED_wpaint_blend_tool(const int tool,
-                           /* dw->weight */
                            const float weight,
                            const float paintval,
                            const float alpha)