Cleanup: move public doc-strings into headers for 'blenkernel'

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 258 insertions, 6 deletions

diff --git a/source/blender/blenkernel/BKE_object.h b/source/blender/blenkernel/BKE_object.h
index 6e1486be0be..3f4268f2169 100644
--- a/source/blender/blenkernel/BKE_object.h
+++ b/source/blender/blenkernel/BKE_object.h
@@ -52,6 +52,14 @@ struct View3D;
 struct ViewLayer;
 
 void BKE_object_workob_clear(struct Object *workob);
+/**
+ * For calculation of the inverse parent transform, only used for editor.
+ *
+ * It assumes the object parent is already in the depsgraph.
+ * Otherwise, after changing ob->parent you need to call:
+ * - #DEG_relations_tag_update(bmain);
+ * - #BKE_scene_graph_update_tagged(depsgraph, bmain);
+ */
 void BKE_object_workob_calc_parent(struct Depsgraph *depsgraph,
                                    struct Scene *scene,
                                    struct Object *ob,
@@ -67,6 +75,9 @@ void BKE_object_free_particlesystems(struct Object *ob);
 void BKE_object_free_softbody(struct Object *ob);
 void BKE_object_free_curve_cache(struct Object *ob);
 
+/**
+ * Free data derived from mesh, called when mesh changes or is freed.
+ */
 void BKE_object_free_derived_caches(struct Object *ob);
 void BKE_object_free_caches(struct Object *object);
 
@@ -77,19 +88,55 @@ bool BKE_object_modifier_gpencil_use_time(struct Object *ob, struct GpencilModif
 
 bool BKE_object_shaderfx_use_time(struct Object *ob, struct ShaderFxData *fx);
 
+/**
+ * \return True if the object's type supports regular modifiers (not grease pencil modifiers).
+ */
 bool BKE_object_supports_modifiers(const struct Object *ob);
 bool BKE_object_support_modifier_type_check(const struct Object *ob, int modifier_type);
 
 /* Active modifier. */
+
+/**
+ * Set the object's active modifier.
+ *
+ * \param md: If nullptr, only clear the active modifier, otherwise
+ * it must be in the #Object.modifiers list.
+ */
 void BKE_object_modifier_set_active(struct Object *ob, struct ModifierData *md);
 struct ModifierData *BKE_object_active_modifier(const struct Object *ob);
 
+/**
+ * Copy a single modifier.
+ *
+ * \note *Do not* use this function to copy a whole modifier stack (see note below too). Use
+ * `BKE_object_modifier_stack_copy` instead.
+ *
+ * \note Complex modifiers relaying on other data (like e.g. dynamic paint or fluid using particle
+ * systems) are not always 100% 'correctly' copied here, since we have to use heuristics to decide
+ * which particle system to use or add in `ob_dst`, and it's placement in the stack, etc. If used
+ * more than once, this function should preferably be called in stack order.
+ */
 bool BKE_object_copy_modifier(struct Main *bmain,
                               struct Scene *scene,
                               struct Object *ob_dst,
                               const struct Object *ob_src,
                               struct ModifierData *md);
+/**
+ * Copy a single GPencil modifier.
+ *
+ * \note *Do not* use this function to copy a whole modifier stack. Use
+ * `BKE_object_modifier_stack_copy` instead.
+ */
 bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, struct GpencilModifierData *gmd_src);
+/**
+ * Copy the whole stack of modifiers from one object into another.
+ *
+ * \warning *Does not* clear modifier stack and related data (particle systems, soft-body,
+ * etc.) in `ob_dst`, if needed calling code must do it.
+ *
+ * \param do_copy_all: If true, even modifiers that should not support copying (like Hook one)
+ * will be duplicated.
+ */
 bool BKE_object_modifier_stack_copy(struct Object *ob_dst,
                                     const struct Object *ob_src,
                                     const bool do_copy_all,
@@ -98,6 +145,12 @@ void BKE_object_link_modifiers(struct Object *ob_dst, const struct Object *ob_sr
 void BKE_object_free_modifiers(struct Object *ob, const int flag);
 void BKE_object_free_shaderfx(struct Object *ob, const int flag);
 
+/**
+ * Proxy rule:
+ * - `lib_object->proxy_from` == the one we borrow from, set temporally while object_update.
+ * - `local_object->proxy` == pointer to library object, saved in files and read.
+ * - `local_object->proxy_group` == pointer to collection dupli-object, saved in files and read.
+ */
 void BKE_object_make_proxy(struct Main *bmain,
                            struct Object *ob,
                            struct Object *target,
@@ -105,6 +158,9 @@ void BKE_object_make_proxy(struct Main *bmain,
 void BKE_object_copy_proxy_drivers(struct Object *ob, struct Object *target);
 
 bool BKE_object_exists_check(struct Main *bmain, const struct Object *obtest);
+/**
+ * Actual check for internal data, not context or flags.
+ */
 bool BKE_object_is_in_editmode(const struct Object *ob);
 bool BKE_object_is_in_editmode_vgroup(const struct Object *ob);
 bool BKE_object_is_in_wpaint_select_vert(const struct Object *ob);
@@ -115,6 +171,9 @@ bool BKE_object_data_is_in_editmode(const struct ID *id);
 
 char *BKE_object_data_editmode_flush_ptr_get(struct ID *id);
 
+/**
+ * Updates select_id of all objects in the given \a bmain.
+ */
 void BKE_object_update_select_id(struct Main *bmain);
 
 typedef enum eObjectVisibilityResult {
@@ -124,14 +183,33 @@ typedef enum eObjectVisibilityResult {
   OB_VISIBLE_ALL = (OB_VISIBLE_SELF | OB_VISIBLE_PARTICLES | OB_VISIBLE_INSTANCES),
 } eObjectVisibilityResult;
 
+/**
+ * Return which parts of the object are visible, as evaluated by depsgraph.
+ */
 int BKE_object_visibility(const struct Object *ob, const int dag_eval_mode);
 
+/**
+ * More general add: creates minimum required data, but without vertices etc.
+ */
 struct Object *BKE_object_add_only_object(struct Main *bmain, int type, const char *name)
     ATTR_NONNULL(1) ATTR_RETURNS_NONNULL;
+/**
+ * General add: to scene, with layer from area and default name.
+ *
+ * Object is added to the active #Collection.
+ * If there is no linked collection to the active #ViewLayer we create a new one.
+ *
+ * \note Creates minimum required data, but without vertices etc.
+ */
 struct Object *BKE_object_add(struct Main *bmain,
                               struct ViewLayer *view_layer,
                               int type,
                               const char *name) ATTR_NONNULL(1, 2) ATTR_RETURNS_NONNULL;
+/**
+ * Add a new object, using another one as a reference
+ *
+ * \param ob_src: object to use to determine the collections of the new object.
+ */
 struct Object *BKE_object_add_from(struct Main *bmain,
                                    struct Scene *scene,
                                    struct ViewLayer *view_layer,
@@ -139,6 +217,15 @@ struct Object *BKE_object_add_from(struct Main *bmain,
                                    const char *name,
                                    struct Object *ob_src)
     ATTR_NONNULL(1, 2, 3, 6) ATTR_RETURNS_NONNULL;
+/**
+ * Add a new object, but assign the given data-block as the `ob->data`
+ * for the newly created object.
+ *
+ * \param data: The data-block to assign as `ob->data` for the new object.
+ * This is assumed to be of the correct type.
+ * \param do_id_user: If true, #id_us_plus() will be called on data when
+ * assigning it to the object.
+ */
 struct Object *BKE_object_add_for_data(struct Main *bmain,
                                        struct ViewLayer *view_layer,
                                        int type,
@@ -147,16 +234,39 @@ struct Object *BKE_object_add_for_data(struct Main *bmain,
                                        bool do_id_user) ATTR_RETURNS_NONNULL;
 void *BKE_object_obdata_add_from_type(struct Main *bmain, int type, const char *name)
     ATTR_NONNULL(1);
+/**
+ * Return -1 on failure.
+ */
 int BKE_object_obdata_to_type(const struct ID *id) ATTR_NONNULL(1);
 
+/**
+ * Returns true if the Object is from an external blend file (libdata).
+ */
 bool BKE_object_is_libdata(const struct Object *ob);
+/**
+ * Returns true if the Object data is from an external blend file (libdata).
+ */
 bool BKE_object_obdata_is_libdata(const struct Object *ob);
 
+/**
+ * Perform deep-copy of object and its 'children' data-blocks (obdata, materials, actions, etc.).
+ *
+ * \param dupflag: Controls which sub-data are also duplicated
+ * (see #eDupli_ID_Flags in DNA_userdef_types.h).
+ *
+ * \note This function does not do any remapping to new IDs, caller must do it
+ * (\a #BKE_libblock_relink_to_newid()).
+ * \note Caller MUST free \a newid pointers itself (#BKE_main_id_newptr_and_tag_clear()) and call
+ * updates of DEG too (#DAG_relations_tag_update()).
+ */
 struct Object *BKE_object_duplicate(struct Main *bmain,
                                     struct Object *ob,
                                     uint dupflag,
                                     uint duplicate_options);
 
+/**
+ * Use with newly created objects to set their size (used to apply scene-scale).
+ */
 void BKE_object_obdata_size_init(struct Object *ob, const float size);
 
 void BKE_object_scale_to_mat3(struct Object *ob, float r_mat[3][3]);
@@ -168,6 +278,16 @@ void BKE_object_apply_mat4(struct Object *ob,
                            const float mat[4][4],
                            const bool use_compat,
                            const bool use_parent);
+/**
+ * Applies the global transformation \a mat to the \a ob using a relative parent space if
+ * supplied.
+ *
+ * \param mat: the global transformation mat that the object should be set object to.
+ * \param parent: the parent space in which this object will be set relative to
+ * (should probably always be parent_eval).
+ * \param use_compat: true to ensure that rotations are set using the
+ * min difference between the old and new orientation.
+ */
 void BKE_object_apply_mat4_ex(struct Object *ob,
                               const float mat[4][4],
                               struct Object *parent,
@@ -181,6 +301,9 @@ struct Object *BKE_object_pose_armature_get_visible(struct Object *ob,
                                                     struct ViewLayer *view_layer,
                                                     struct View3D *v3d);
 
+/**
+ * Access pose array with special check to get pose object when in weight paint mode.
+ */
 struct Object **BKE_object_pose_array_get_ex(struct ViewLayer *view_layer,
                                              struct View3D *v3d,
                                              unsigned int *r_objects_len,
@@ -205,7 +328,9 @@ struct Base **BKE_object_pose_base_array_get(struct ViewLayer *view_layer,
 
 void BKE_object_get_parent_matrix(struct Object *ob, struct Object *par, float r_parentmat[4][4]);
 
-/* Compute object world transform and store it in ob->obmat. */
+/**
+ * Compute object world transform and store it in `ob->obmat`.
+ */
 void BKE_object_where_is_calc(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob);
 void BKE_object_where_is_calc_ex(struct Depsgraph *depsgraph,
                                  struct Scene *scene,
@@ -216,9 +341,16 @@ void BKE_object_where_is_calc_time(struct Depsgraph *depsgraph,
                                    struct Scene *scene,
                                    struct Object *ob,
                                    float ctime);
+/**
+ * Calculate object transformation matrix without recalculating dependencies and
+ * constraints -- assume dependencies are already solved by depsgraph.
+ * No changes to object and its parent would be done.
+ * Used for bundles orientation in 3d space relative to parented blender camera.
+ */
 void BKE_object_where_is_calc_mat4(struct Object *ob, float r_obmat[4][4]);
 
 /* Possibly belong in own module? */
+
 struct BoundBox *BKE_boundbox_alloc_unit(void);
 void BKE_boundbox_init_from_minmax(struct BoundBox *bb, const float min[3], const float max[3]);
 void BKE_boundbox_calc_center_aabb(const struct BoundBox *bb, float r_cent[3]);
@@ -230,6 +362,14 @@ void BKE_boundbox_minmax(const struct BoundBox *bb,
 
 struct BoundBox *BKE_object_boundbox_get(struct Object *ob);
 void BKE_object_dimensions_get(struct Object *ob, float r_vec[3]);
+/**
+ * The original scale and object matrix can be passed in so any difference
+ * of the objects matrix and the final matrix can be accounted for,
+ * typically this caused by parenting, constraints or delta-scale.
+ *
+ * Re-using these values from the object causes a feedback loop
+ * when multiple values are modified at once in some situations. see: T69536.
+ */
 void BKE_object_dimensions_set_ex(struct Object *ob,
                                   const float value[3],
                                   int axis_mask,
@@ -238,6 +378,9 @@ void BKE_object_dimensions_set_ex(struct Object *ob,
 void BKE_object_dimensions_set(struct Object *ob, const float value[3], int axis_mask);
 
 void BKE_object_empty_draw_type_set(struct Object *ob, const int value);
+/**
+ * Use this to temporally disable/enable bound-box.
+ */
 void BKE_object_boundbox_flag(struct Object *ob, int flag, const bool set);
 void BKE_object_boundbox_calc_from_mesh(struct Object *ob, const struct Mesh *me_eval);
 bool BKE_object_boundbox_calc_from_evaluated_geometry(struct Object *ob);
@@ -249,7 +392,9 @@ bool BKE_object_minmax_dupli(struct Depsgraph *depsgraph,
                              float r_max[3],
                              const bool use_hidden);
 
-/* sometimes min-max isn't enough, we need to loop over each point */
+/**
+ * Sometimes min-max isn't enough, we need to loop over each point.
+ */
 void BKE_object_foreach_display_point(struct Object *ob,
                                       const float obmat[4][4],
                                       void (*func_cb)(const float[3], void *),
@@ -280,9 +425,18 @@ void BKE_object_tfm_protected_restore(struct Object *ob,
 
 void BKE_object_tfm_copy(struct Object *object_dst, const struct Object *object_src);
 
+/**
+ * Restore the object->data to a non-modifier evaluated state.
+ *
+ * Some changes done directly in evaluated object require them to be reset
+ * before being re-evaluated.
+ * For example, we need to call this before #BKE_mesh_new_from_object(),
+ * in case we removed/added modifiers in the evaluated object.
+ */
 void BKE_object_eval_reset(struct Object *ob_eval);
 
 /* Dependency graph evaluation callbacks. */
+
 void BKE_object_eval_local_transform(struct Depsgraph *depsgraph, struct Object *ob);
 void BKE_object_eval_parent(struct Depsgraph *depsgraph, struct Object *ob);
 void BKE_object_eval_constraints(struct Depsgraph *depsgraph,
@@ -295,6 +449,9 @@ void BKE_object_eval_uber_transform(struct Depsgraph *depsgraph, struct Object *
 void BKE_object_eval_uber_data(struct Depsgraph *depsgraph,
                                struct Scene *scene,
                                struct Object *ob);
+/**
+ * Assign #Object.data after modifier stack evaluation.
+ */
 void BKE_object_eval_assign_data(struct Object *object, struct ID *data, bool is_owned);
 
 void BKE_object_sync_to_original(struct Depsgraph *depsgraph, struct Object *object);
@@ -320,7 +477,27 @@ void BKE_object_eval_eval_base_flags(struct Depsgraph *depsgraph,
 void BKE_object_handle_data_update(struct Depsgraph *depsgraph,
                                    struct Scene *scene,
                                    struct Object *ob);
+/**
+ * \warning "scene" here may not be the scene object actually resides in.
+ * When dealing with background-sets, "scene" is actually the active scene.
+ * e.g. "scene" <-- set 1 <-- set 2 ("ob" lives here) <-- set 3 <-- ... <-- set n
+ * rigid bodies depend on their world so use #BKE_object_handle_update_ex()
+ * to also pass along the current rigid body world.
+ */
 void BKE_object_handle_update(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob);
+/**
+ * Proxy rule:
+ * - lib_object->proxy_from == the one we borrow from, only set temporal and cleared here.
+ * - local_object->proxy    == pointer to library object, saved in files and read.
+ *
+ * Function below is polluted with proxy exceptions, cleanup will follow!
+ *
+ * The main object update call, for object matrix, constraints, keys and displist (modifiers)
+ * requires flags to be set!
+ *
+ * Ideally we shouldn't have to pass the rigid body world,
+ * but need bigger restructuring to avoid id.
+ */
 void BKE_object_handle_update_ex(struct Depsgraph *depsgraph,
                                  struct Scene *scene,
                                  struct Object *ob,
@@ -334,13 +511,28 @@ bool BKE_object_obdata_texspace_get(struct Object *ob,
                                     float **r_loc,
                                     float **r_size);
 
+/** Get evaluated mesh for given object. */
 struct Mesh *BKE_object_get_evaluated_mesh(const struct Object *object);
+/**
+ * Get mesh which is not affected by modifiers:
+ * - For original objects it will be same as `object->data`, and it is a mesh
+ *   which is in the corresponding #Main.
+ * - For copied-on-write objects it will give pointer to a copied-on-write
+ *   mesh which corresponds to original object's mesh.
+ */
 struct Mesh *BKE_object_get_pre_modified_mesh(const struct Object *object);
+/**
+ * Get a mesh which corresponds to the very original mesh from #Main.
+ * - For original objects it will be object->data.
+ * - For evaluated objects it will be same mesh as corresponding original
+ *   object uses as data.
+ */
 struct Mesh *BKE_object_get_original_mesh(const struct Object *object);
 
 /* Lattice accessors.
  * These functions return either the regular lattice, or the edit-mode lattice,
  * whichever is currently in use. */
+
 struct Lattice *BKE_object_get_lattice(const struct Object *object);
 struct Lattice *BKE_object_get_evaluated_lattice(const struct Object *object);
 
@@ -357,12 +549,38 @@ bool BKE_object_flag_test_recursive(const struct Object *ob, short flag);
 
 bool BKE_object_is_child_recursive(const struct Object *ob_parent, const struct Object *ob_child);
 
-/* return ModifierMode flag */
+/**
+ * Most important if this is modified it should _always_ return true, in certain
+ * cases false positives are hard to avoid (shape keys for example).
+ *
+ * \return #ModifierMode flag.
+ */
 int BKE_object_is_modified(struct Scene *scene, struct Object *ob);
+/**
+ * Test if object is affected by deforming modifiers (for motion blur). again
+ * most important is to avoid false positives, this is to skip computations
+ * and we can still if there was actual deformation afterwards.
+ */
 int BKE_object_is_deform_modified(struct Scene *scene, struct Object *ob);
 
+/**
+ * Check of objects moves in time.
+ *
+ * \note This function is currently optimized for usage in combination
+ * with modifier deformation checks (#eModifierTypeType_OnlyDeform),
+ * so modifiers can quickly check if their target objects moves
+ * (causing deformation motion blur) or not.
+ *
+ * This makes it possible to give some degree of false-positives here,
+ * but it's currently an acceptable tradeoff between complexity and check
+ * speed. In combination with checks of modifier stack and real life usage
+ * percentage of false-positives shouldn't be that high.
+ *
+ * \note This function does not consider physics systems.
+ */
 bool BKE_object_moves_in_time(const struct Object *object, bool recurse_parent);
 
+/** Return the number of scenes using (instantiating) that object in their collections. */
 int BKE_object_scenes_users_get(struct Main *bmain, struct Object *ob);
 
 struct MovieClip *BKE_object_movieclip_get(struct Scene *scene,
@@ -370,7 +588,16 @@ struct MovieClip *BKE_object_movieclip_get(struct Scene *scene,
                                            bool use_default);
 
 void BKE_object_runtime_reset(struct Object *object);
+/**
+ * Reset all pointers which we don't want to be shared when copying the object.
+ */
 void BKE_object_runtime_reset_on_copy(struct Object *object, const int flag);
+/**
+ * The function frees memory used by the runtime data, but not the runtime field itself.
+ *
+ * All runtime data is cleared to ensure it's not used again,
+ * in keeping with other `_free_data(..)` functions.
+ */
 void BKE_object_runtime_free_data(struct Object *object);
 
 void BKE_object_batch_cache_dirty_tag(struct Object *ob);
@@ -394,12 +621,31 @@ typedef enum eObjectSet {
   OB_SET_ALL,      /* All Objects. */
 } eObjectSet;
 
+/**
+ * Iterates over all objects of the given scene layer.
+ * Depending on the #eObjectSet flag:
+ * collect either #OB_SET_ALL, #OB_SET_VISIBLE or #OB_SET_SELECTED objects.
+ * If #OB_SET_VISIBLE or#OB_SET_SELECTED are collected,
+ * then also add related objects according to the given \a includeFilter.
+ */
 struct LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer,
                                                 eObjectSet objectSet,
                                                 eObRelationTypes includeFilter);
+/**
+ * \return All groups this object is a part of, caller must free.
+ */
 struct LinkNode *BKE_object_groups(struct Main *bmain, struct Scene *scene, struct Object *ob);
 void BKE_object_groups_clear(struct Main *bmain, struct Scene *scene, struct Object *object);
 
+/**
+ * Return a KDTree_3d from the deformed object (in world-space).
+ *
+ * \note Only mesh objects currently support deforming, others are TODO.
+ *
+ * \param ob:
+ * \param r_tot:
+ * \return The KD-tree or nullptr if it can't be created.
+ */
 struct KDTree_3d *BKE_object_as_kdtree(struct Object *ob, int *r_tot);
 
 bool BKE_object_modifier_use_time(struct Scene *scene,
@@ -407,6 +653,10 @@ bool BKE_object_modifier_use_time(struct Scene *scene,
                                   struct ModifierData *md,
                                   int dag_eval_mode);
 
+/**
+ * \note this function should eventually be replaced by depsgraph functionality.
+ * Avoid calling this in new code unless there is a very good reason for it!
+ */
 bool BKE_object_modifier_update_subframe(struct Depsgraph *depsgraph,
                                          struct Scene *scene,
                                          struct Object *ob,
@@ -420,7 +670,8 @@ bool BKE_object_empty_image_frame_is_visible_in_view3d(const struct Object *ob,
 bool BKE_object_empty_image_data_is_visible_in_view3d(const struct Object *ob,
                                                       const struct RegionView3D *rv3d);
 
-/* This is an utility function for Python's object.to_mesh() (the naming is not very clear though).
+/**
+ * This is an utility function for Python's object.to_mesh() (the naming is not very clear though).
  * The result is owned by the object.
  *
  * The mesh will be freed when object is re-evaluated or is destroyed. It is possible to force to
@@ -437,11 +688,12 @@ struct Mesh *BKE_object_to_mesh(struct Depsgraph *depsgraph,
 
 void BKE_object_to_mesh_clear(struct Object *object);
 
-/* This is an utility function for Python's object.to_curve().
+/**
+ * This is an utility function for Python's `object.to_curve()`.
  * The result is owned by the object.
  *
  * The curve will be freed when object is re-evaluated or is destroyed. It is possible to force
- * clear memory used by this curve by calling BKE_object_to_curve_clear().
+ * clear memory used by this curve by calling #BKE_object_to_curve_clear().
  *
  * If apply_modifiers is true and the object is a curve one, then spline deform modifiers are
  * applied on the curve control points.