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

Ref T92709

1 files changed, 155 insertions, 6 deletions

diff --git a/source/blender/editors/include/ED_object.h b/source/blender/editors/include/ED_object.h
index 2a557f1abd3..576c6f51362 100644
--- a/source/blender/editors/include/ED_object.h
+++ b/source/blender/editors/include/ED_object.h
@@ -56,12 +56,24 @@ struct wmOperator;
 struct wmOperatorType;
 
 /* object_edit.c */
-/* context.object */
+
+/** `context.object` */
 struct Object *ED_object_context(const struct bContext *C);
-/* context.object or context.active_object */
+/**
+ * Find the correct active object per context (`context.object` or `context.active_object`)
+ * \note context can be NULL when called from a enum with #PROP_ENUM_NO_CONTEXT.
+ */
 struct Object *ED_object_active_context(const struct bContext *C);
 void ED_collection_hide_menu_draw(const struct bContext *C, struct uiLayout *layout);
 
+/**
+ * Return an array of objects:
+ * - When in the property space, return the pinned or active object.
+ * - When in edit-mode/pose-mode, return an array of objects in the mode.
+ * - Otherwise return selected objects,
+ *   the callers \a filter_fn needs to check of they are editable
+ *   (assuming they need to be modified).
+ */
 Object **ED_object_array_in_mode_or_selected(struct bContext *C,
                                              bool (*filter_fn)(const struct Object *ob,
                                                                void *user_data),
@@ -81,6 +93,10 @@ bool ED_object_calc_active_center(struct Object *ob, const bool select_only, flo
 struct XFormObjectData_Container;
 struct XFormObjectData_Container *ED_object_data_xform_container_create(void);
 void ED_object_data_xform_container_destroy(struct XFormObjectData_Container *xds);
+/**
+ * This may be called multiple times with the same data.
+ * Each time, the original transformations are re-applied, instead of accumulating the changes.
+ */
 void ED_object_data_xform_container_update_all(struct XFormObjectData_Container *xds,
                                                struct Main *bmain,
                                                struct Depsgraph *depsgraph);
@@ -130,6 +146,7 @@ void ED_operatormacros_object(void);
 void ED_keymap_object(struct wmKeyConfig *keyconf);
 
 /* object_relations.c */
+
 typedef enum eParentType {
   PAR_OBJECT,
   PAR_ARMATURE,
@@ -163,7 +180,9 @@ extern struct EnumPropertyItem prop_clear_parent_types[];
 extern struct EnumPropertyItem prop_make_parent_types[];
 #endif
 
-/* Set the object's parent, return true if successful. */
+/**
+ * Set the object's parent, return true if successful.
+ */
 bool ED_object_parent_set(struct ReportList *reports,
                           const struct bContext *C,
                           struct Scene *scene,
@@ -175,13 +194,35 @@ bool ED_object_parent_set(struct ReportList *reports,
                           const int vert_par[3]);
 void ED_object_parent_clear(struct Object *ob, const int type);
 
+/**
+ * Simple API for object selection, rather than just using the flag
+ * this takes into account the 'restrict selection in 3d view' flag.
+ * deselect works always, the restriction just prevents selection
+ *
+ * \note Caller must send a `NC_SCENE | ND_OB_SELECT` notifier
+ * (or a `NC_SCENE | ND_OB_VISIBLE` in case of visibility toggling).
+ */
 void ED_object_base_select(struct Base *base, eObjectSelect_Mode mode);
+/**
+ * Change active base, it includes the notifier
+ */
 void ED_object_base_activate(struct bContext *C, struct Base *base);
 void ED_object_base_activate_with_mode_exit_if_needed(struct bContext *C, struct Base *base);
+/**
+ * Call when the active base has changed.
+ */
 void ED_object_base_active_refresh(struct Main *bmain,
                                    struct Scene *scene,
                                    struct ViewLayer *view_layer);
+/**
+ * Remove base from a specific scene.
+ * \note now unlinks constraints as well.
+ */
 void ED_object_base_free_and_unlink(struct Main *bmain, struct Scene *scene, struct Object *ob);
+/**
+ * Remove base from a specific scene.
+ * `ob` must not be indirectly used.
+ */
 void ED_object_base_free_and_unlink_no_indirect_check(struct Main *bmain,
                                                       struct Scene *scene,
                                                       struct Object *ob);
@@ -191,7 +232,13 @@ bool ED_object_base_deselect_all_ex(struct ViewLayer *view_layer,
                                     bool *r_any_visible);
 bool ED_object_base_deselect_all(struct ViewLayer *view_layer, struct View3D *v3d, int action);
 
-/* single object duplicate, if (dupflag == 0), fully linked, else it uses the flags given */
+/**
+ * Single object duplicate, if `dupflag == 0`, fully linked, else it uses the flags given.
+ * Leaves selection of base/object unaltered.
+ * \note don't call this within a loop since clear_* funcs loop over the entire database.
+ * \note caller must do `DAG_relations_tag_update(bmain);`
+ * this is not done automatic since we may duplicate many objects in a batch.
+ */
 struct Base *ED_object_add_duplicate(struct Main *bmain,
                                      struct Scene *scene,
                                      struct ViewLayer *view_layer,
@@ -211,12 +258,21 @@ enum {
   EM_FREEDATA = (1 << 0),
   EM_NO_CONTEXT = (1 << 1),
 };
+/**
+ * \param flag:
+ * - If #EM_FREEDATA isn't in the flag, use ED_object_editmode_load directly.
+ */
 bool ED_object_editmode_exit_ex(struct Main *bmain,
                                 struct Scene *scene,
                                 struct Object *obedit,
                                 int flag);
 bool ED_object_editmode_exit(struct bContext *C, int flag);
 
+/**
+ * Support freeing edit-mode data without flushing it back to the object.
+ *
+ * \return true if data was freed.
+ */
 bool ED_object_editmode_free_ex(struct Main *bmain, struct Object *obedit);
 
 bool ED_object_editmode_exit_multi_ex(struct Main *bmain,
@@ -284,6 +340,10 @@ void ED_object_rotation_from_view(struct bContext *C, float rot[3], const char a
 void ED_object_base_init_transform_on_add(struct Object *object,
                                           const float loc[3],
                                           const float rot[3]);
+/**
+ * Uses context to figure out transform for primitive.
+ * Returns standard diameter.
+ */
 float ED_object_new_primitive_matrix(struct bContext *C,
                                      struct Object *obedit,
                                      const float loc[3],
@@ -291,8 +351,9 @@ float ED_object_new_primitive_matrix(struct bContext *C,
                                      const float scale[3],
                                      float primmat[4][4]);
 
-/* Avoid allowing too much insane values even by typing
- * (typos can hang/crash Blender otherwise). */
+/**
+ * Avoid allowing too much insane values even by typing (typos can hang/crash Blender otherwise).
+ */
 #define OBJECT_ADD_SIZE_MAXF 1.0e12f
 
 void ED_object_add_unit_props_size(struct wmOperatorType *ot);
@@ -310,6 +371,12 @@ bool ED_object_add_generic_get_opts(struct bContext *C,
                                     unsigned short *r_local_view_bits,
                                     bool *r_is_view_aligned);
 
+/**
+ * For object add primitive operators, or for object creation when `obdata != NULL`.
+ * \param obdata: Assigned to #Object.data, with increased user count.
+ *
+ * \note Do not call undo push in this function (users of this function have to).
+ */
 struct Object *ED_object_add_type_with_obdata(struct bContext *C,
                                               const int type,
                                               const char *name,
@@ -327,9 +394,16 @@ struct Object *ED_object_add_type(struct bContext *C,
                                   const unsigned short local_view_bits)
     ATTR_NONNULL(1) ATTR_RETURNS_NONNULL;
 
+/**
+ * Not an especially efficient function, only added so the single user button can be functional.
+ */
 void ED_object_single_user(struct Main *bmain, struct Scene *scene, struct Object *ob);
 
 /* object motion paths */
+
+/**
+ * Clear motion paths for all objects.
+ */
 void ED_objects_clear_paths(struct bContext *C, bool only_selected);
 
 /* Corresponds to eAnimvizCalcRange. */
@@ -339,6 +413,12 @@ typedef enum eObjectPathCalcRange {
   OBJECT_PATH_CALC_RANGE_FULL,
 } eObjectPathCalcRange;
 
+/**
+ * For the objects with animation: update paths for those that have got them
+ * This should selectively update paths that exist.
+ *
+ * To be called from various tools that do incremental updates
+ */
 void ED_objects_recalculate_paths(struct bContext *C,
                                   struct Scene *scene,
                                   eObjectPathCalcRange range,
@@ -353,11 +433,26 @@ void ED_objects_recalculate_paths_visible(struct bContext *C,
                                           eObjectPathCalcRange range);
 
 /* constraints */
+/**
+ * If object is in pose-mode, return active bone constraints, else object constraints.
+ * No constraints are returned for a bone on an inactive bone-layer.
+ */
 struct ListBase *ED_object_constraint_active_list(struct Object *ob);
+/**
+ * Get the constraints for the active pose bone. Bone may be on an inactive bone-layer
+ * (unlike #ED_object_constraint_active_list, such constraints are not excluded here).
+ */
 struct ListBase *ED_object_pose_constraint_list(const struct bContext *C);
+/**
+ * Find the list that a given constraint belongs to,
+ * and/or also get the posechannel this is from (if applicable).
+ */
 struct ListBase *ED_object_constraint_list_from_constraint(struct Object *ob,
                                                            struct bConstraint *con,
                                                            struct bPoseChannel **r_pchan);
+/**
+ * Single constraint.
+ */
 struct bConstraint *ED_object_constraint_active_get(struct Object *ob);
 
 void object_test_constraints(struct Main *bmain, struct Object *ob);
@@ -389,7 +484,17 @@ void ED_object_constraint_copy_for_pose(struct Main *bmain,
                                         struct bConstraint *con);
 
 /* object_modes.c */
+
+/**
+ * Checks the mode to be set is compatible with the object
+ * should be made into a generic function
+ */
 bool ED_object_mode_compat_test(const struct Object *ob, eObjectMode mode);
+/**
+ * Sets the mode to a compatible state (use before entering the mode).
+ *
+ * This is so each mode's exec function can call
+ */
 bool ED_object_mode_compat_set(struct bContext *C,
                                struct Object *ob,
                                eObjectMode mode,
@@ -412,11 +517,18 @@ void ED_object_posemode_set_for_weight_paint(struct bContext *C,
                                              const bool is_mode_set);
 
 /* object_modifier.c */
+
 enum {
   MODIFIER_APPLY_DATA = 1,
   MODIFIER_APPLY_SHAPE,
 };
 
+/**
+ * Add a modifier to given object, including relevant extra processing needed by some physics types
+ * (particles, simulations...).
+ *
+ * \param scene: is only used to set current frame in some cases, and may be NULL.
+ */
 struct ModifierData *ED_object_modifier_add(struct ReportList *reports,
                                             struct Main *bmain,
                                             struct Scene *scene,
@@ -465,12 +577,25 @@ void ED_object_modifier_copy_to_object(struct bContext *C,
                                        struct Object *ob_src,
                                        struct ModifierData *md);
 
+/**
+ * If the object data of 'orig_ob' has other users, run 'callback' on
+ * each of them.
+ *
+ * If include_orig is true, the callback will run on 'orig_ob' too.
+ *
+ * If the callback ever returns true, iteration will stop and the
+ * function value will be true. Otherwise the function returns false.
+ */
 bool ED_object_iter_other(struct Main *bmain,
                           struct Object *orig_ob,
                           const bool include_orig,
                           bool (*callback)(struct Object *ob, void *callback_data),
                           void *callback_data);
 
+/**
+ * Use with #ED_object_iter_other(). Sets the total number of levels
+ * for any multi-res modifiers on the object to the int pointed to by callback_data.
+ */
 bool ED_object_multires_update_totlevels_cb(struct Object *ob, void *totlevel_v);
 
 /* object_greasepencil_modifier.c */
@@ -546,16 +671,40 @@ void ED_object_check_force_modifiers(struct Main *bmain,
                                      struct Scene *scene,
                                      struct Object *object);
 
+/**
+ * If id is not already an Object, try to find an object that uses it as data.
+ * Prefers active, then selected, then visible/selectable.
+ */
 struct Base *ED_object_find_first_by_data_id(struct ViewLayer *view_layer, struct ID *id);
 
+/**
+ * Select and make the target object active in the view layer.
+ * If already selected, selection isn't changed.
+ *
+ * \returns false if not found in current view layer
+ */
 bool ED_object_jump_to_object(struct bContext *C, struct Object *ob, const bool reveal_hidden);
+/**
+ * Select and make the target object and bone active.
+ * Switches to Pose mode if in Object mode so the selection is visible.
+ * Un-hides the target bone and bone layer if necessary.
+ *
+ * \returns false if object not in layer, bone not found, or other error
+ */
 bool ED_object_jump_to_bone(struct bContext *C,
                             struct Object *ob,
                             const char *bone_name,
                             const bool reveal_hidden);
 
 /* object_facemap_ops.c */
+
+/**
+ * Called while not in edit-mode.
+ */
 void ED_object_facemap_face_add(struct Object *ob, struct bFaceMap *fmap, int facenum);
+/**
+ * Called while not in edit-mode.
+ */
 void ED_object_facemap_face_remove(struct Object *ob, struct bFaceMap *fmap, int facenum);
 
 /* object_data_transform.c */