Cleanup: move public doc-strings into headers for various API's

Some doc-strings were skipped because of blank-lines between
the doc-string and the symbol and needed to be moved manually.

- 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.

Ref T92709

1 files changed, 65 insertions, 15 deletions

diff --git a/source/blender/editors/armature/armature_intern.h b/source/blender/editors/armature/armature_intern.h
index 3a6761ba915..77607cedcb1 100644
--- a/source/blender/editors/armature/armature_intern.h
+++ b/source/blender/editors/armature/armature_intern.h
@@ -39,8 +39,10 @@ struct bArmature;
 struct LinkData;
 struct ListBase;
 
-/* ******************************************************* */
-/* Armature EditMode Operators */
+/* -------------------------------------------------------------------- */
+/** \name Armature EditMode Operators
+ * \{ */
+
 void ARMATURE_OT_bone_primitive_add(struct wmOperatorType *ot);
 
 void ARMATURE_OT_align(struct wmOperatorType *ot);
@@ -82,8 +84,12 @@ void ARMATURE_OT_layers_show_all(struct wmOperatorType *ot);
 void ARMATURE_OT_armature_layers(struct wmOperatorType *ot);
 void ARMATURE_OT_bone_layers(struct wmOperatorType *ot);
 
-/* ******************************************************* */
-/* Pose-Mode Operators */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Pose-Mode Operators
+ * \{ */
+
 void POSE_OT_hide(struct wmOperatorType *ot);
 void POSE_OT_reveal(struct wmOperatorType *ot);
 
@@ -131,8 +137,12 @@ void POSE_OT_quaternions_flip(struct wmOperatorType *ot);
 
 void POSE_OT_bone_layers(struct wmOperatorType *ot);
 
-/* ******************************************************* */
-/* Pose Tool Utilities (for PoseLib, Pose Sliding, etc.) */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Pose Tool Utilities (for PoseLib, Pose Sliding, etc.)
+ * \{ */
+
 /* pose_utils.c */
 
 /* Temporary data linking PoseChannels with the F-Curves they affect */
@@ -173,21 +183,39 @@ typedef struct tPChanFCurveLink {
 
 /* ----------- */
 
+/** Returns a valid pose armature for this object, else returns NULL. */
 struct Object *poseAnim_object_get(struct Object *ob_);
+/** Get sets of F-Curves providing transforms for the bones in the Pose. */
 void poseAnim_mapping_get(struct bContext *C, ListBase *pfLinks);
+/** Free F-Curve <-> PoseChannel links. */
 void poseAnim_mapping_free(ListBase *pfLinks);
 
+/**
+ * Helper for apply() / reset() - refresh the data.
+ */
 void poseAnim_mapping_refresh(struct bContext *C, struct Scene *scene, struct Object *ob);
+/**
+ * Reset changes made to current pose.
+ */
 void poseAnim_mapping_reset(ListBase *pfLinks);
+/** Perform auto-key-framing after changes were made + confirmed. */
 void poseAnim_mapping_autoKeyframe(struct bContext *C,
                                    struct Scene *scene,
                                    ListBase *pfLinks,
                                    float cframe);
 
+/**
+ * Find the next F-Curve for a PoseChannel with matching path...
+ * - path is not just the pfl rna_path, since that path doesn't have property info yet.
+ */
 LinkData *poseAnim_mapping_getNextFCurve(ListBase *fcuLinks, LinkData *prev, const char *path);
 
-/* ******************************************************* */
-/* PoseLib */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name PoseLib
+ * \{ */
+
 /* pose_lib.c */
 
 void POSELIB_OT_new(struct wmOperatorType *ot);
@@ -207,8 +235,12 @@ void POSELIB_OT_apply_pose(struct wmOperatorType *ot);
 void POSELIB_OT_apply_pose_asset(struct wmOperatorType *ot);
 void POSELIB_OT_blend_pose_asset(struct wmOperatorType *ot);
 
-/* ******************************************************* */
-/* Pose Sliding Tools */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Pose Sliding Tools
+ * \{ */
+
 /* pose_slide.c */
 
 void POSE_OT_push(struct wmOperatorType *ot);
@@ -220,8 +252,11 @@ void POSE_OT_blend_to_neighbors(struct wmOperatorType *ot);
 
 void POSE_OT_propagate(struct wmOperatorType *ot);
 
-/* ******************************************************* */
-/* Various Armature Edit/Pose Editing API's */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Various Armature Edit/Pose Editing API's
+ * \{ */
 
 /* Ideally, many of these defines would not be needed as everything would be strictly
  * self-contained within each file,
@@ -232,7 +267,9 @@ struct EditBone *make_boneList(struct ListBase *edbo,
                                struct ListBase *bones,
                                struct Bone *actBone);
 
-/* duplicate method */
+/* Duplicate method. */
+
+/** Call this before doing any duplications. */
 void preEditBoneDuplicate(struct ListBase *editbones);
 void postEditBoneDuplicate(struct ListBase *editbones, struct Object *ob);
 struct EditBone *duplicateEditBone(struct EditBone *cur_bone,
@@ -240,20 +277,29 @@ struct EditBone *duplicateEditBone(struct EditBone *cur_bone,
                                    struct ListBase *editbones,
                                    struct Object *ob);
 
-/* duplicate method (cross objects) */
-/* editbones is the target list */
+/* Duplicate method (cross objects). */
+
+/**
+ * \param editbones: The target list.
+ */
 struct EditBone *duplicateEditBoneObjects(struct EditBone *cur_bone,
                                           const char *name,
                                           struct ListBase *editbones,
                                           struct Object *src_ob,
                                           struct Object *dst_ob);
 
+/** Adds an EditBone between the nominated locations (should be in the right space). */
 struct EditBone *add_points_bone(struct Object *obedit, float head[3], float tail[3]);
 void bone_free(struct bArmature *arm, struct EditBone *bone);
 
 void armature_tag_select_mirrored(struct bArmature *arm);
+/**
+ * Helper function for tools to work on mirrored parts.
+ * it leaves mirrored bones selected then too, which is a good indication of what happened.
+ */
 void armature_select_mirrored_ex(struct bArmature *arm, const int flag);
 void armature_select_mirrored(struct bArmature *arm);
+/** Only works when tagged. */
 void armature_tag_unselect(struct bArmature *arm);
 
 struct EditBone *ED_armature_pick_ebone(struct bContext *C,
@@ -291,6 +337,10 @@ struct Bone *ED_armature_pick_bone_from_selectbuffer(struct Base **bases,
                                                      bool do_nearest,
                                                      struct Base **r_base);
 
+/**
+ * XXX: bone_looper is only to be used when we want to access settings
+ * (i.e. editability/visibility/selected) that context doesn't offer.
+ */
 int bone_looper(struct Object *ob,
                 struct Bone *bone,
                 void *data,