[Bf-blender-cvs] [240f15c1b6e] master: Comments: improve docstring for ED_view3d_clipping_test

[Campbell Barton]

Commit: 240f15c1b6eff3dc174c9abe5e2956b7e397beaa
Author: Campbell Barton
Date:   Mon Mar 29 18:28:26 2021 +1100
Branches: master
https://developer.blender.org/rB240f15c1b6eff3dc174c9abe5e2956b7e397beaa

Comments: improve docstring for ED_view3d_clipping_test

The meaning of the return value wasn't obvious.

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

M	source/blender/editors/space_view3d/view3d_draw.c

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

diff --git a/source/blender/editors/space_view3d/view3d_draw.c b/source/blender/editors/space_view3d/view3d_draw.c
index a46d093c039..1be20c21aba 100644
--- a/source/blender/editors/space_view3d/view3d_draw.c
+++ b/source/blender/editors/space_view3d/view3d_draw.c
@@ -2146,8 +2146,15 @@ static bool view3d_clipping_test(const float co[3], const float clip[6][4])
   return true;
 }
 
-/* For 'local' ED_view3d_clipping_local must run first
- * then all comparisons can be done in localspace. */
+/**
+ * Return true when `co` is hidden by the 3D views clipping planes.
+ *
+ * \param local: When true use local (object-space) #ED_view3d_clipping_local must run first,
+ * then all comparisons can be done in local-space.
+ * \return True when `co` is outside all clipping planes.
+ *
+ * \note Callers should check #RV3D_CLIPPING_ENABLED first.
+ */
 bool ED_view3d_clipping_test(const RegionView3D *rv3d, const float co[3], const bool is_local)
 {
   return view3d_clipping_test(co, is_local ? rv3d->clip_local : rv3d->clip);