[Bf-blender-cvs] [143a7cf0550] temp-collection-assets: Cleanup: Improve comments

[Julian Eisel]

Commit: 143a7cf055088efa2302253847db3df9ab54a86c
Author: Julian Eisel
Date:   Tue Jan 18 11:50:09 2022 +0100
Branches: temp-collection-assets
https://developer.blender.org/rB143a7cf055088efa2302253847db3df9ab54a86c

Cleanup: Improve comments

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

M	source/blender/blenkernel/BKE_collection.h
M	source/blender/editors/space_view3d/space_view3d.c

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

diff --git a/source/blender/blenkernel/BKE_collection.h b/source/blender/blenkernel/BKE_collection.h
index 35d8c93d2b0..33e5705bcbc 100644
--- a/source/blender/blenkernel/BKE_collection.h
+++ b/source/blender/blenkernel/BKE_collection.h
@@ -228,17 +228,31 @@ struct Base *BKE_collection_or_layer_objects(const struct ViewLayer *view_layer,
 /* Dimensions. */
 
 /**
- * Calculate the axis-aligned bounding box (in global space) of all objects in this collection,
+ * Calculate an axis-aligned bounding box (in global space) of all objects in this collection,
  * excluding empties (but including lamps, cameras, curves, etc.). Nested collections and
  * collection instances are included.
+ *
+ * \warning This is not a reliable bounding box for things like collision detection. For example,
+ *          it doesn't consider particle instances or grease pencil stroke width.
+ *          Take it as approximation, e.g. for visual feedback.
+ *
+ * \param object_visibility: Sets what object visibility is required (e.g. decide between viewport
+ *                           vs. render visibility).
  */
 void BKE_collection_boundbox_calc(const struct Collection *collection,
                                   CollectionObjectVisibility object_visibility,
                                   struct BoundBox *r_boundbox);
 /**
- * Calculate the axis-aligned dimensions of all objects in this collection, excluding
- * empties (but including lamps, cameras, curves, etc.). Nested collections and collection
- * instances are included.
+ * Calculate axis-aligned dimensions of all objects in this collection, excluding empties (but
+ * including lamps, cameras, curves, etc.). Nested collections and collection instances are
+ * included.
+ *
+ * \warning This is not a reliable bounding box for things like collision detection. For example,
+ *          it doesn't consider particle instances or grease pencil stroke width.
+ *          Take it as approximation, e.g. for visual feedback.
+ *
+ * \param object_visibility: Sets what object visibility is required (e.g. decide between viewport
+ *                           vs. render visibility).
  */
 void BKE_collection_dimensions_calc(const struct Collection *collection,
                                     CollectionObjectVisibility object_visibility,
diff --git a/source/blender/editors/space_view3d/space_view3d.c b/source/blender/editors/space_view3d/space_view3d.c
index b4705619bee..a15bab0a5ef 100644
--- a/source/blender/editors/space_view3d/space_view3d.c
+++ b/source/blender/editors/space_view3d/space_view3d.c
@@ -915,6 +915,7 @@ static void view3d_dropboxes(void)
   ListBase *lb = WM_dropboxmap_find("View3D", SPACE_VIEW3D, RGN_TYPE_WINDOW);
 
   struct wmDropBox *drop;
+  /* Local object. */
   drop = WM_dropbox_add(lb,
                         "OBJECT_OT_add_named",
                         view3d_ob_drop_poll_local_id,
@@ -925,6 +926,7 @@ static void view3d_dropboxes(void)
   drop->draw_activate = view3d_boundbox_drop_draw_activate;
   drop->draw_deactivate = view3d_boundbox_drop_draw_deactivate;
 
+  /* Object asset from external file. */
   drop = WM_dropbox_add(lb,
                         "OBJECT_OT_transform_to_mouse",
                         view3d_ob_drop_poll_external_asset,
@@ -935,6 +937,7 @@ static void view3d_dropboxes(void)
   drop->draw_activate = view3d_boundbox_drop_draw_activate;
   drop->draw_deactivate = view3d_boundbox_drop_draw_deactivate;
 
+  /* Local collection (adds collection instance). */
   drop = WM_dropbox_add(lb,
                         "OBJECT_OT_collection_instance_add",
                         view3d_collection_drop_poll_local_id,
@@ -945,14 +948,16 @@ static void view3d_dropboxes(void)
   drop->draw_activate = view3d_boundbox_drop_draw_activate;
   drop->draw_deactivate = view3d_boundbox_drop_draw_deactivate;
 
-  /* Use OBJECT_OT_transform_to_mouse for collection instances as well, to transform the instance
-   * empty. Just needs different callbacks than objects. */
-  drop = WM_dropbox_add(lb,
-                        "OBJECT_OT_transform_to_mouse",
-                        view3d_collection_drop_poll_external_asset,
-                        view3d_collection_instance_drop_copy_external_asset,
-                        WM_drag_free_imported_drag_ID,
-                        NULL);
+  /* Collection asset from external file (adds collection instance). */
+  drop = WM_dropbox_add(
+      lb,
+      /* Use OBJECT_OT_transform_to_mouse for collection instances as well, to transform the
+       * instance empty. Just needs different callbacks than objects. */
+      "OBJECT_OT_transform_to_mouse",
+      view3d_collection_drop_poll_external_asset,
+      view3d_collection_instance_drop_copy_external_asset,
+      WM_drag_free_imported_drag_ID,
+      NULL);
   drop->draw = WM_drag_draw_item_name_fn;
   drop->draw_activate = view3d_boundbox_drop_draw_activate;
   drop->draw_deactivate = view3d_boundbox_drop_draw_deactivate;