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

6 files changed, 555 insertions, 128 deletions

diff --git a/source/blender/editors/include/ED_armature.h b/source/blender/editors/include/ED_armature.h
index 868235c36e5..0053bf5c865 100644
--- a/source/blender/editors/include/ED_armature.h
+++ b/source/blender/editors/include/ED_armature.h
@@ -70,45 +70,91 @@ struct wmOperator;
   (CHECK_TYPE_INLINE(ebone, EditBone *), \
    (((ebone)->flag & BONE_SELECTED) && !((ebone)->flag & BONE_EDITMODE_LOCKED)))
 
-/* used in armature_select.c and pose_select.c */
+/* Used in `armature_select.c` and `pose_select.c`. */
+
 #define BONE_SELECT_PARENT 0
 #define BONE_SELECT_CHILD 1
 
 /* armature_add.c */
+
+/**
+ * Default bone add, returns it selected, but without tail set.
+ *
+ * \note should be used everywhere, now it allocates bones still locally in functions.
+ */
 struct EditBone *ED_armature_ebone_add(struct bArmature *arm, const char *name);
 struct EditBone *ED_armature_ebone_add_primitive(struct Object *obedit_arm,
                                                  float length,
                                                  bool view_aligned);
 
 /* armature_edit.c */
+
+/**
+ * Adjust bone roll to align Z axis with vector `align_axis` is in local space and is normalized.
+ */
 float ED_armature_ebone_roll_to_vector(const struct EditBone *bone,
                                        const float align_axis[3],
                                        const bool axis_only);
+/**
+ * \param centermode: 0 == do center, 1 == center new, 2 == center cursor.
+ *
+ * \note Exported for use in `editors/object/`.
+ */
 void ED_armature_origin_set(
     struct Main *bmain, struct Object *ob, const float cursor[3], int centermode, int around);
+/**
+ * See #BKE_armature_transform for object-mode transform.
+ */
 void ED_armature_edit_transform(struct bArmature *arm, const float mat[4][4], const bool do_props);
 void ED_armature_transform(struct bArmature *arm, const float mat[4][4], const bool do_props);
 
 /* armature_naming.c */
+
+/**
+ * Ensure the bone name is unique.
+ * If bone is already in list, pass it as argument to ignore it.
+ */
 void ED_armature_ebone_unique_name(struct ListBase *ebones, char *name, struct EditBone *bone);
+
+/**
+ * Bone Rename (called by UI for renaming a bone).
+ * Seems messy, but that's what you get with not using pointers but channel names :).
+ * \warning make sure the original bone was not renamed yet!
+ */
 void ED_armature_bone_rename(struct Main *bmain,
                              struct bArmature *arm,
                              const char *oldnamep,
                              const char *newnamep);
+/**
+ * Renames (by flipping) all selected bones at once.
+ *
+ * This way if we are flipping related bones (e.g., Bone.L, Bone.R) at the same time
+ * all the bones are safely renamed, without conflicting with each other.
+ *
+ * \param arm: Armature the bones belong to
+ * \param bones_names: List of bone conflict elements (#LinkData pointing to names).
+ * \param do_strip_numbers: if set, try to get rid of dot-numbers at end of bone names.
+ */
 void ED_armature_bones_flip_names(struct Main *bmain,
                                   struct bArmature *arm,
                                   struct ListBase *bones_names,
                                   const bool do_strip_numbers);
 
 /* armature_ops.c */
+
 void ED_operatortypes_armature(void);
 void ED_operatormacros_armature(void);
 void ED_keymap_armature(struct wmKeyConfig *keyconf);
 
 /* armature_relations.c */
+
+/**
+ * Join armature exec is exported for use in object->join objects operator.
+ */
 int ED_armature_join_objects_exec(struct bContext *C, struct wmOperator *op);
 
 /* armature_select.c */
+
 struct Base *ED_armature_base_and_ebone_from_select_buffer(struct Base **bases,
                                                            uint bases_len,
                                                            int hit,
@@ -121,6 +167,9 @@ struct Base *ED_armature_base_and_pchan_from_select_buffer(struct Base **bases,
                                                            uint bases_len,
                                                            int hit,
                                                            struct bPoseChannel **r_pchan);
+/**
+ * For callers that don't need the pose channel.
+ */
 struct Base *ED_armature_base_and_bone_from_select_buffer(struct Base **bases,
                                                           uint bases_len,
                                                           int hit,
@@ -137,11 +186,27 @@ bool ED_armature_edit_select_pick_bone(struct bContext *C,
                                        bool extend,
                                        bool deselect,
                                        bool toggle);
+/**
+ * Bone selection picking for armature edit-mode in the view3d.
+ */
 bool ED_armature_edit_select_pick(
     struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle);
+/**
+ * Perform a selection operation on elements which have been 'touched',
+ * use for lasso & border select but can be used elsewhere too.
+ *
+ * Tagging is done via #EditBone.temp.i using: #BONESEL_ROOT, #BONESEL_TIP, #BONESEL_BONE
+ * And optionally ignoring end-points using the #BONESEL_ROOT, #BONESEL_TIP right shifted 16 bits.
+ * (used when the values are clipped outside the view).
+ *
+ * \param sel_op: #eSelectOp type.
+ *
+ * \note Visibility checks must be done by the caller.
+ */
 bool ED_armature_edit_select_op_from_tagged(struct bArmature *arm, const int sel_op);
 
 /* armature_skinning.c */
+
 #define ARM_GROUPS_NAME 1
 #define ARM_GROUPS_ENVELOPE 2
 #define ARM_GROUPS_AUTO 3
@@ -154,40 +219,74 @@ void ED_object_vgroup_calc_from_armature(struct ReportList *reports,
                                          const bool mirror);
 
 /* editarmature_undo.c */
+
+/** Export for ED_undo_sys. */
 void ED_armature_undosys_type(struct UndoType *ut);
 
 /* armature_utils.c */
+
+/** Sync selection to parent for connected children. */
 void ED_armature_edit_sync_selection(struct ListBase *edbo);
 void ED_armature_edit_validate_active(struct bArmature *arm);
+/**
+ * Update the layers_used variable after bones are moved between layer
+ * \note Used to be done in drawing code in 2.7, but that won't work with
+ * Copy-on-Write, as drawing uses evaluated copies.
+ */
 void ED_armature_edit_refresh_layer_used(struct bArmature *arm);
+/**
+ * \param clear_connected: When false caller is responsible for keeping the flag in a valid state.
+ */
 void ED_armature_ebone_remove_ex(struct bArmature *arm,
                                  struct EditBone *exBone,
                                  bool clear_connected);
 void ED_armature_ebone_remove(struct bArmature *arm, struct EditBone *exBone);
 bool ED_armature_ebone_is_child_recursive(struct EditBone *ebone_parent,
                                           struct EditBone *ebone_child);
+/**
+ * Finds the first parent shared by \a ebone_child
+ *
+ * \param ebone_child: Children bones to search
+ * \param ebone_child_tot: Size of the ebone_child array
+ * \return The shared parent or NULL.
+ */
 struct EditBone *ED_armature_ebone_find_shared_parent(struct EditBone *ebone_child[],
                                                       const unsigned int ebone_child_tot);
 void ED_armature_ebone_to_mat3(struct EditBone *ebone, float r_mat[3][3]);
 void ED_armature_ebone_to_mat4(struct EditBone *ebone, float r_mat[4][4]);
 void ED_armature_ebone_from_mat3(struct EditBone *ebone, const float mat[3][3]);
 void ED_armature_ebone_from_mat4(struct EditBone *ebone, const float mat[4][4]);
+/**
+ * Return a pointer to the bone of the given name
+ */
 struct EditBone *ED_armature_ebone_find_name(const struct ListBase *edbo, const char *name);
+/**
+ * \see #BKE_pose_channel_get_mirrored (pose-mode, matching function)
+ */
 struct EditBone *ED_armature_ebone_get_mirrored(const struct ListBase *edbo, struct EditBone *ebo);
 void ED_armature_ebone_transform_mirror_update(struct bArmature *arm,
                                                struct EditBone *ebo,
                                                bool check_select);
+/**
+ * If edit-bone (partial) selected, copy data.
+ * context; edit-mode armature, with mirror editing enabled.
+ */
 void ED_armature_edit_transform_mirror_update(struct Object *obedit);
+/** Put edit-mode back in Object. */
 void ED_armature_from_edit(struct Main *bmain, struct bArmature *arm);
+/** Put armature in edit-mode. */
 void ED_armature_to_edit(struct bArmature *arm);
 void ED_armature_edit_free(struct bArmature *arm);
 void ED_armature_ebone_listbase_temp_clear(struct ListBase *lb);
+
+/**
+ * Free's bones and their properties.
+ */
 void ED_armature_ebone_listbase_free(struct ListBase *lb, const bool do_id_user);
 void ED_armature_ebone_listbase_copy(struct ListBase *lb_dst,
                                      struct ListBase *lb_src,
                                      const bool do_id_user);
 
-/* low level selection functions which handle */
 int ED_armature_ebone_selectflag_get(const struct EditBone *ebone);
 void ED_armature_ebone_selectflag_set(struct EditBone *ebone, int flag);
 void ED_armature_ebone_select_set(struct EditBone *ebone, bool select);
@@ -198,21 +297,29 @@ void ED_armature_ebone_selectflag_disable(struct EditBone *ebone, int flag);
 struct Object *ED_pose_object_from_context(struct bContext *C);
 bool ED_object_posemode_exit_ex(struct Main *bmain, struct Object *ob);
 bool ED_object_posemode_exit(struct bContext *C, struct Object *ob);
+/** This function is used to process the necessary updates for. */
 bool ED_object_posemode_enter_ex(struct Main *bmain, struct Object *ob);
 bool ED_object_posemode_enter(struct bContext *C, struct Object *ob);
 
-/* Corresponds to eAnimvizCalcRange. */
+/** Corresponds to #eAnimvizCalcRange. */
 typedef enum ePosePathCalcRange {
   POSE_PATH_CALC_RANGE_CURRENT_FRAME,
   POSE_PATH_CALC_RANGE_CHANGED,
   POSE_PATH_CALC_RANGE_FULL,
 } ePosePathCalcRange;
+/**
+ * For the object with pose/action: 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_pose_recalculate_paths(struct bContext *C,
                                struct Scene *scene,
                                struct Object *ob,
                                ePosePathCalcRange range);
 
 /* pose_select.c */
+
 void ED_armature_pose_select_pick_bone(struct ViewLayer *view_layer,
                                        struct View3D *v3d,
                                        struct Object *ob,
@@ -220,6 +327,10 @@ void ED_armature_pose_select_pick_bone(struct ViewLayer *view_layer,
                                        bool extend,
                                        bool deselect,
                                        bool toggle);
+/**
+ * Called for mode-less pose selection.
+ * assumes the active object is still on old situation.
+ */
 bool ED_armature_pose_select_pick_with_buffer(struct ViewLayer *view_layer,
                                               struct View3D *v3d,
                                               struct Base *base,
@@ -229,6 +340,14 @@ bool ED_armature_pose_select_pick_with_buffer(struct ViewLayer *view_layer,
                                               bool deselect,
                                               bool toggle,
                                               bool do_nearest);
+/**
+ * While in weight-paint mode, a single pose may be active as well.
+ * While not common, it's possible we have multiple armatures deforming a mesh.
+ *
+ * This function de-selects all other objects, and selects the new base.
+ * It can't be set to the active object because we need
+ * to keep this set to the weight paint object.
+ */
 void ED_armature_pose_select_in_wpaint_mode(struct ViewLayer *view_layer,
                                             struct Base *base_select);
 bool ED_pose_deselect_all_multi_ex(struct Base **bases,
@@ -236,8 +355,16 @@ bool ED_pose_deselect_all_multi_ex(struct Base **bases,
                                    int select_mode,
                                    const bool ignore_visibility);
 bool ED_pose_deselect_all_multi(struct bContext *C, int select_mode, const bool ignore_visibility);
+/**
+ * 'select_mode' is usual SEL_SELECT/SEL_DESELECT/SEL_TOGGLE/SEL_INVERT.
+ * When true, 'ignore_visibility' makes this func also affect invisible bones
+ * (hidden or on hidden layers).
+ */
 bool ED_pose_deselect_all(struct Object *ob, int select_mode, const bool ignore_visibility);
 void ED_pose_bone_select_tag_update(struct Object *ob);
+/**
+ * Utility method for changing the selection status of a bone.
+ */
 void ED_pose_bone_select(struct Object *ob, struct bPoseChannel *pchan, bool select);
 
 /* meshlaplacian.c */
@@ -249,7 +376,9 @@ void ED_mesh_deform_bind_callback(struct MeshDeformModifierData *mmd,
 
 /* Pose backups, pose_backup.c */
 struct PoseBackup;
-/* Create a backup of those bones that are animated in the given action. */
+/**
+ * Create a backup of those bones that are animated in the given action.
+ */
 struct PoseBackup *ED_pose_backup_create_selected_bones(
     const struct Object *ob, const struct bAction *action) ATTR_WARN_UNUSED_RESULT;
 struct PoseBackup *ED_pose_backup_create_all_bones(
diff --git a/source/blender/editors/include/ED_keyframes_edit.h b/source/blender/editors/include/ED_keyframes_edit.h
index e29ff3ed890..76ba2ebf4a6 100644
--- a/source/blender/editors/include/ED_keyframes_edit.h
+++ b/source/blender/editors/include/ED_keyframes_edit.h
@@ -39,7 +39,9 @@ struct bDopeSheet;
 /* ************************************************ */
 /* Common Macros and Defines */
 
-/* --------- Tool Flags ------------ */
+/* -------------------------------------------------------------------- */
+/** \name Tool Flags
+ * \{ */
 
 /* bezt validation */
 typedef enum eEditKeyframes_Validate {
@@ -60,7 +62,7 @@ typedef enum eEditKeyframes_Validate {
   BEZT_OK_CHANNEL_CIRCLE,
 } eEditKeyframes_Validate;
 
-/* ------------ */
+/** \} */
 
 /* select modes */
 typedef enum eEditKeyframes_Select {
@@ -120,7 +122,9 @@ typedef struct KeyframeEdit_CircleData {
 /* ************************************************ */
 /* Non-Destructive Editing API (keyframes_edit.c) */
 
-/* --- Defines for 'OK' polls + KeyframeEditData Flags --------- */
+/* -------------------------------------------------------------------- */
+/** \name Defines for 'OK' polls + KeyframeEditData Flags
+ * \{ */
 
 /* which verts of a keyframe is active (after polling) */
 typedef enum eKeyframeVertOk {
@@ -154,7 +158,11 @@ typedef enum eKeyframeIterFlags {
   KEYFRAME_ITER_HANDLES_DEFAULT_INVISIBLE = (1 << 3),
 } eKeyframeIterFlags;
 
-/* --- Generic Properties for Keyframe Edit Tools ----- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Generic Properties for Keyframe Edit Tools
+ * \{ */
 
 typedef struct KeyframeEditData {
   /* generic properties/data access */
@@ -184,14 +192,22 @@ typedef struct KeyframeEditData {
   eKeyframeIterFlags iterflags;
 } KeyframeEditData;
 
-/* ------- Function Pointer Typedefs ---------------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Function Pointer Typedefs
+ * \{ */
 
 /* callback function that refreshes the F-Curve after use */
 typedef void (*FcuEditFunc)(struct FCurve *fcu);
 /* callback function that operates on the given BezTriple */
 typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt);
 
-/* ------- Custom Data Type Defines ------------------ */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Custom Data Type Defines
+ * \{ */
 
 /* Custom data for remapping one range to another in a fixed way */
 typedef struct KeyframeEditCD_Remap {
@@ -222,18 +238,29 @@ typedef enum eKeyMergeMode {
   KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL,
 } eKeyMergeMode;
 
-/* ---------------- Looping API --------------------- */
+/** \} */
 
-/* functions for looping over keyframes */
-/* function for working with F-Curve data only
- * (i.e. when filters have been chosen to explicitly use this) */
+/* -------------------------------------------------------------------- */
+/** \name Looping API
+ *
+ * Functions for looping over keyframes.
+ * \{ */
+
+/**
+ * This function is used to loop over BezTriples in the given F-Curve, applying a given
+ * operation on them, and optionally applies an F-Curve validation function afterwards.
+ *
+ * function for working with F-Curve data only
+ * (i.e. when filters have been chosen to explicitly use this).
+ */
 short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked,
                                  struct FCurve *fcu,
                                  KeyframeEditFunc key_ok,
                                  KeyframeEditFunc key_cb,
                                  FcuEditFunc fcu_cb);
-/* function for working with any type (i.e. one of the known types) of animation channel
- * - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG)
+/**
+ * Function for working with any type (i.e. one of the known types) of animation channel
+ * \param filterflag: is bDopeSheet->flag (#DOPESHEET_FILTERFLAG).
  */
 short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked,
                                       struct bDopeSheet *ads,
@@ -241,8 +268,9 @@ short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked,
                                       KeyframeEditFunc key_ok,
                                       KeyframeEditFunc key_cb,
                                       FcuEditFunc fcu_cb);
-/* same as above, except bAnimListElem wrapper is not needed...
- * - keytype is eAnim_KeyType
+/**
+ * Same as above, except bAnimListElem wrapper is not needed...
+ * \param keytype: is eAnim_KeyType.
  */
 short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked,
                                           struct bDopeSheet *ads,
@@ -252,55 +280,92 @@ short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked,
                                           KeyframeEditFunc key_cb,
                                           FcuEditFunc fcu_cb);
 
-/* Calls callback_fn() for each keyframe in each fcurve in the filtered animation context.
- * Assumes the callback updates keys. */
+/**
+ * Calls callback_fn() for each keyframe in each fcurve in the filtered animation context.
+ * Assumes the callback updates keys.
+ */
 void ANIM_animdata_keyframe_callback(struct bAnimContext *ac,
                                      eAnimFilter_Flags filter,
                                      KeyframeEditFunc callback_fn);
 
-/* functions for making sure all keyframes are in good order */
+/**
+ * Functions for making sure all keyframes are in good order.
+ */
 void ANIM_editkeyframes_refresh(struct bAnimContext *ac);
 
-/* ----------- BezTriple Callback Getters ---------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name BezTriple Callback Getters
+ * \{ */
 
 /* accessories */
 KeyframeEditFunc ANIM_editkeyframes_ok(short mode);
 
 /* edit */
 KeyframeEditFunc ANIM_editkeyframes_snap(short mode);
+/**
+ * \note for markers and 'value', the values to use must be supplied as the first float value.
+ */
 KeyframeEditFunc ANIM_editkeyframes_mirror(short mode);
 KeyframeEditFunc ANIM_editkeyframes_select(short mode);
+/**
+ * Set all selected Bezier Handles to a single type.
+ */
 KeyframeEditFunc ANIM_editkeyframes_handles(short mode);
+/**
+ * Set the interpolation type of the selected BezTriples in each F-Curve to the specified one.
+ */
 KeyframeEditFunc ANIM_editkeyframes_ipo(short mode);
 KeyframeEditFunc ANIM_editkeyframes_keytype(short mode);
 KeyframeEditFunc ANIM_editkeyframes_easing(short mode);
 
-/* -------- BezTriple Callbacks (Selection Map) ---------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name BezTriple Callbacks (Selection Map)
+ * \{ */
 
-/* Get a callback to populate the selection settings map
- * requires: ked->custom = char[] of length fcurve->totvert
+/**
+ * Get a callback to populate the selection settings map
+ * requires: ked->custom = char[] of length fcurve->totvert.
  */
 KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode);
 
-/* Change the selection status of the keyframe based on the map entry for this vert
- * requires: ked->custom = char[] of length fcurve->totvert
+/**
+ * Change the selection status of the keyframe based on the map entry for this vert
+ * requires: ked->custom = char[] of length fcurve->totvert.
  */
 short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt);
 
-/* ----------- BezTriple Callback (Assorted Utilities) ---------- */
+/** \} */
 
-/* used to calculate the average location of all relevant BezTriples by summing their locations */
+/* -------------------------------------------------------------------- */
+/** \name BezTriple Callback (Assorted Utilities)
+ * \{ */
+
+/**
+ * Used to calculate the average location of all relevant BezTriples by summing their locations.
+ */
 short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt);
 
-/* used to extract a set of cfra-elems from the keyframes */
+/**
+ * Used to extract a set of cfra-elems from the keyframes.
+ */
 short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt);
 
-/* used to remap times from one range to another
- * requires:  ked->custom = KeyframeEditCD_Remap
+/**
+ * Used to remap times from one range to another.
+ * requires: `ked->custom = KeyframeEditCD_Remap`.
  */
 void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt);
 
-/* ------ 1.5-D Region Testing Utilities (Lasso/Circle Select) ------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name 1.5-D Region Testing Utilities (Lasso/Circle Select)
+ * \{ */
+
 /* XXX: These are temporary,
  * until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */
 
@@ -321,6 +386,9 @@ void clean_fcurve(struct bAnimContext *ac,
                   float thresh,
                   bool cleardefault);
 bool decimate_fcurve(struct bAnimListElem *ale, float remove_ratio, float error_sq_max);
+/**
+ * Use a weighted moving-means method to reduce intensity of fluctuations.
+ */
 void smooth_fcurve(struct FCurve *fcu);
 void sample_fcurve(struct FCurve *fcu);
 
@@ -336,6 +404,8 @@ short paste_animedit_keys(struct bAnimContext *ac,
 
 /* ************************************************ */
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/editors/include/ED_keyframing.h b/source/blender/editors/include/ED_keyframing.h
index 673f629d6ef..d539c7b688c 100644
--- a/source/blender/editors/include/ED_keyframing.h
+++ b/source/blender/editors/include/ED_keyframing.h
@@ -53,22 +53,28 @@ struct PropertyRNA;
 
 struct NlaKeyframingContext;
 
-/* ************ Keyframing Management **************** */
+/* -------------------------------------------------------------------- */
+/** \name Key-Framing Management
+ * \{ */
 
-/* Get the active settings for keyframing settings from context (specifically the given scene)
- * - use_autokey_mode: include settings from keyframing mode in the result (i.e. replace only).
+/**
+ * Get the active settings for key-framing settings from context (specifically the given scene)
+ * \param use_autokey_mode: include settings from key-framing mode in the result
+ * (i.e. replace only).
  */
 eInsertKeyFlags ANIM_get_keyframing_flags(struct Scene *scene, const bool use_autokey_mode);
 
 /* -------- */
 
-/* Get (or add relevant data to be able to do so) the Active Action for the given
+/**
+ * Get (or add relevant data to be able to do so) the Active Action for the given
  * Animation Data block, given an ID block where the Animation Data should reside.
  */
 struct bAction *ED_id_action_ensure(struct Main *bmain, struct ID *id);
 
-/* Get (or add relevant data to be able to do so) F-Curve from the given Action.
- * This assumes that all the destinations are valid.
+/**
+ * Get (or add relevant data to be able to do so) F-Curve from the Active Action,
+ * for the given Animation Data block. This assumes that all the destinations are valid.
  */
 struct FCurve *ED_action_fcurve_ensure(struct Main *bmain,
                                        struct bAction *act,
@@ -77,15 +83,21 @@ struct FCurve *ED_action_fcurve_ensure(struct Main *bmain,
                                        const char rna_path[],
                                        const int array_index);
 
+/**
+ * Find the F-Curve from the Active Action,
+ * for the given Animation Data block. This assumes that all the destinations are valid.
+ */
 struct FCurve *ED_action_fcurve_find(struct bAction *act,
                                      const char rna_path[],
                                      const int array_index);
 
 /* -------- */
 
-/* Lesser Keyframing API call:
- *  Update integer/discrete flags of the FCurve (used when creating/inserting keyframes,
- *  but also through RNA when editing an ID prop, see T37103).
+/**
+ * \brief Lesser Key-framing API call.
+ *
+ * Update integer/discrete flags of the FCurve (used when creating/inserting keyframes,
+ * but also through RNA when editing an ID prop, see T37103).
  */
 void update_autoflags_fcurve(struct FCurve *fcu,
                              struct bContext *C,
@@ -94,16 +106,34 @@ void update_autoflags_fcurve(struct FCurve *fcu,
 
 /* -------- */
 
-/* Lesser Keyframing API call:
- *  Use this when validation of necessary animation data isn't necessary as it already
- *  exists, and there is a beztriple that can be directly copied into the array.
+/**
+ * \brief Lesser Key-framing API call.
+ *
+ * Use this when validation of necessary animation data isn't necessary as it already
+ * exists, and there is a #BezTriple that can be directly copied into the array.
+ *
+ * This function adds a given #BezTriple to an F-Curve. It will allocate
+ * memory for the array if needed, and will insert the #BezTriple into a
+ * suitable place in chronological order.
+ *
+ * \note any recalculate of the F-Curve that needs to be done will need to be done by the caller.
  */
 int insert_bezt_fcurve(struct FCurve *fcu, const struct BezTriple *bezt, eInsertKeyFlags flag);
 
-/* Main Keyframing API call:
- *  Use this when validation of necessary animation data isn't necessary as it
- *  already exists. It will insert a keyframe using the current value being keyframed.
- *  Returns the index at which a keyframe was added (or -1 if failed)
+/**
+ * \brief Main Key-framing API call.
+ *
+ * Use this when validation of necessary animation data isn't necessary as it
+ * already exists. It will insert a keyframe using the current value being keyframed.
+ * Returns the index at which a keyframe was added (or -1 if failed).
+ *
+ * This function is a wrapper for #insert_bezt_fcurve(), and should be used when
+ * adding a new keyframe to a curve, when the keyframe doesn't exist anywhere else yet.
+ * It returns the index at which the keyframe was added.
+ *
+ * \param keyframe_type: The type of keyframe (#eBezTriple_KeyframeType).
+ * \param flag: Optional flags (#eInsertKeyFlags) for controlling how keys get added
+ * and/or whether updates get done.
  */
 int insert_vert_fcurve(struct FCurve *fcu,
                        float x,
@@ -113,9 +143,21 @@ int insert_vert_fcurve(struct FCurve *fcu,
 
 /* -------- */
 
-/* Secondary Keyframing API calls:
- * Use this to insert a keyframe using the current value being keyframed, in the
- * nominated F-Curve (no creation of animation data performed). Returns success.
+/**
+ * \brief Secondary Insert Key-framing API call.
+ *
+ * Use this when validation of necessary animation data is not necessary,
+ * since an RNA-pointer to the necessary data being keyframed,
+ * and a pointer to the F-Curve to use have both been provided.
+ *
+ * This function can't keyframe quaternion channels on some NLA strip types.
+ *
+ * \param keytype: The "keyframe type" (eBezTriple_KeyframeType), as shown in the Dope Sheet.
+ *
+ * \param flag: Used for special settings that alter the behavior of the keyframe insertion.
+ * These include the 'visual' key-framing modes, quick refresh,
+ * and extra keyframe filtering.
+ * \return Success.
  */
 bool insert_keyframe_direct(struct ReportList *reports,
                             struct PointerRNA ptr,
@@ -128,9 +170,17 @@ bool insert_keyframe_direct(struct ReportList *reports,
 
 /* -------- */
 
-/* Main Keyframing API calls:
+/**
+ * \brief Main Insert Key-framing API call.
+ *
  * Use this to create any necessary animation data, and then insert a keyframe
- * using the current value being keyframed, in the relevant place. Returns success.
+ * using the current value being keyframed, in the relevant place.
+ *
+ * \param flag: Used for special settings that alter the behavior of the keyframe insertion.
+ * These include the 'visual' key-framing modes, quick refresh, and extra keyframe filtering.
+ *
+ * \param array_index: The index to key or -1 keys all array indices.
+ * \return The number of key-frames inserted.
  */
 int insert_keyframe(struct Main *bmain,
                     struct ReportList *reports,
@@ -144,9 +194,13 @@ int insert_keyframe(struct Main *bmain,
                     struct ListBase *nla_cache,
                     eInsertKeyFlags flag);
 
-/* Main Keyframing API call:
+/**
+ * \brief Main Delete Key-Framing API call.
+ *
  * Use this to delete keyframe on current frame for relevant channel.
- * Will perform checks just in case. */
+ * Will perform checks just in case.
+ * \return The number of key-frames deleted.
+ */
 int delete_keyframe(struct Main *bmain,
                     struct ReportList *reports,
                     struct ID *id,
@@ -155,7 +209,11 @@ int delete_keyframe(struct Main *bmain,
                     int array_index,
                     float cfra);
 
-/* ************ Keying Sets ********************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Keying Sets
+ * \{ */
 
 /* forward decl. for this struct which is declared a bit later... */
 struct ExtensionRNA;
@@ -206,7 +264,9 @@ typedef struct KeyingSetInfo {
 
 /* -------- */
 
-/* Add another data source for Relative Keying Sets to be evaluated with */
+/**
+ * Add another data source for Relative Keying Sets to be evaluated with.
+ */
 void ANIM_relative_keyingset_add_source(ListBase *dsources,
                                         struct ID *id,
                                         struct StructRNA *srna,
@@ -226,13 +286,28 @@ typedef enum eModifyKey_Returns {
   MODIFYKEY_MISSING_TYPEINFO = -2,
 } eModifyKey_Returns;
 
-/* poll the current KeyingSet, updating its set of paths
- * (if "builtin"/"relative") for context changes */
+/**
+ * Given a #KeyingSet and context info, validate Keying Set's paths.
+ * This is only really necessary with relative/built-in KeyingSets
+ * where their list of paths is dynamically generated based on the
+ * current context info.
+ *
+ * \return 0 if succeeded, otherwise an error code: #eModifyKey_Returns.
+ */
 eModifyKey_Returns ANIM_validate_keyingset(struct bContext *C,
                                            ListBase *dsources,
                                            struct KeyingSet *ks);
 
-/* use the specified KeyingSet to add/remove various Keyframes on the specified frame */
+/**
+ * Use the specified #KeyingSet and context info (if required)
+ * to add/remove various Keyframes on the specified frame.
+ *
+ * Modify keyframes for the channels specified by the KeyingSet.
+ * This takes into account many of the different combinations of using KeyingSets.
+ *
+ * \returns the number of channels that key-frames were added or
+ * an #eModifyKey_Returns value (always a negative number).
+ */
 int ANIM_apply_keyingset(struct bContext *C,
                          ListBase *dsources,
                          struct bAction *act,
@@ -242,49 +317,88 @@ int ANIM_apply_keyingset(struct bContext *C,
 
 /* -------- */
 
-/* Get the first builtin KeyingSet with the given name, which occurs after the given one
- * (or start of list if none given) */
+/**
+ * Find builtin #KeyingSet by name.
+ *
+ * \return The first builtin #KeyingSet with the given name, which occurs after the given one
+ * (or start of list if none given).
+ */
 struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]);
 
-/* Find KeyingSet type info given a name */
+/**
+ * Find KeyingSet type info given a name.
+ */
 KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]);
 
-/* Find a given ID in the KeyingSet */
+/**
+ * Check if the ID appears in the paths specified by the #KeyingSet.
+ */
 bool ANIM_keyingset_find_id(struct KeyingSet *ks, ID *id);
 
-/* for RNA type registrations... */
+/**
+ * Add the given KeyingSetInfo to the list of type infos,
+ * and create an appropriate builtin set too.
+ */
 void ANIM_keyingset_info_register(KeyingSetInfo *ksi);
+/**
+ * Remove the given #KeyingSetInfo from the list of type infos,
+ * and also remove the builtin set if appropriate.
+ */
 void ANIM_keyingset_info_unregister(struct Main *bmain, KeyingSetInfo *ksi);
 
 /* cleanup on exit */
+/* --------------- */
+
 void ANIM_keyingset_infos_exit(void);
 
 /* -------- */
 
-/* Get the active KeyingSet for the given scene */
+/**
+ * Get the active Keying Set for the given scene.
+ */
 struct KeyingSet *ANIM_scene_get_active_keyingset(const struct Scene *scene);
 
-/* Get the index of the Keying Set provided, for the given Scene */
+/**
+ * Get the index of the Keying Set provided, for the given Scene.
+ */
 int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks);
 
-/* Get Keying Set to use for Auto-Keyframing some transforms */
+/**
+ * Get Keying Set to use for Auto-Key-Framing some transforms.
+ */
 struct KeyingSet *ANIM_get_keyingset_for_autokeying(const struct Scene *scene,
                                                     const char *transformKSName);
 
-/* Dynamically populate an enum of Keying Sets */
+/**
+ * Dynamically populate an enum of Keying Sets.
+ */
 const struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C,
                                                            struct PointerRNA *ptr,
                                                            struct PropertyRNA *prop,
                                                            bool *r_free);
 
-/* Use to get the keying set from the int value used by enums. */
+/**
+ * Get the keying set from enum values generated in #ANIM_keying_sets_enum_itemf.
+ *
+ * Type is the Keying Set the user specified to use when calling the operator:
+ * \param type:
+ * - == 0: use scene's active Keying Set.
+ * -  > 0: use a user-defined Keying Set from the active scene.
+ * -  < 0: use a builtin Keying Set.
+ */
 KeyingSet *ANIM_keyingset_get_from_enum_type(struct Scene *scene, int type);
 KeyingSet *ANIM_keyingset_get_from_idname(struct Scene *scene, const char *idname);
 
-/* Check if KeyingSet can be used in the current context */
+/**
+ * Check if #KeyingSet can be used in the current context.
+ */
 bool ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks);
 
-/* ************ Drivers ********************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Drivers
+ * \{ */
 
 /* Flags for use by driver creation calls */
 typedef enum eCreateDriverFlags {
@@ -311,7 +425,10 @@ typedef enum eCreateDriver_MappingTypes {
   CREATEDRIVER_MAPPING_NONE_ALL = 4,
 } eCreateDriver_MappingTypes;
 
-/* RNA Enum of eCreateDriver_MappingTypes, for use by the appropriate operators */
+/**
+ * Mapping Types enum for operators.
+ * \note Used by #ANIM_OT_driver_button_add and #UI_OT_eyedropper_driver.
+ */
 extern EnumPropertyItem prop_driver_create_mapping_types[];
 
 /* -------- */
@@ -323,7 +440,11 @@ typedef enum eDriverFCurveCreationMode {
   DRIVER_FCURVE_EMPTY = 3        /* Add without data, for pasting. */
 } eDriverFCurveCreationMode;
 
-/* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools,
+/**
+ * Get (or add relevant data to be able to do so) F-Curve from the driver stack,
+ * for the given Animation Data block. This assumes that all the destinations are valid.
+ *
+ * \note This low-level function shouldn't be used directly for most tools,
  * although there are special cases where this approach is preferable.
  */
 struct FCurve *verify_driver_fcurve(struct ID *id,
@@ -337,16 +458,18 @@ struct FCurve *alloc_driver_fcurve(const char rna_path[],
 
 /* -------- */
 
-/* Main Driver Management API calls:
- *  Add a new driver for the specified property on the given ID block,
- *  and make it be driven by the specified target.
+/**
+ * \brief Main Driver Management API calls
+ *
+ * Add a new driver for the specified property on the given ID block,
+ * and make it be driven by the specified target.
  *
  * This is intended to be used in conjunction with a modal "eyedropper"
  * for picking the variable that is going to be used to drive this one.
  *
- * - flag: eCreateDriverFlags
- * - driver_type: eDriver_Types
- * - mapping_type: eCreateDriver_MappingTypes
+ * \param flag: eCreateDriverFlags
+ * \param driver_type: eDriver_Types
+ * \param mapping_type: eCreateDriver_MappingTypes
  */
 int ANIM_add_driver_with_target(struct ReportList *reports,
                                 struct ID *dst_id,
@@ -361,8 +484,10 @@ int ANIM_add_driver_with_target(struct ReportList *reports,
 
 /* -------- */
 
-/* Main Driver Management API calls:
- *  Add a new driver for the specified property on the given ID block
+/**
+ * \brief Main Driver Management API calls.
+ *
+ * Add a new driver for the specified property on the given ID block
  */
 int ANIM_add_driver(struct ReportList *reports,
                     struct ID *id,
@@ -371,90 +496,128 @@ int ANIM_add_driver(struct ReportList *reports,
                     short flag,
                     int type);
 
-/* Main Driver Management API calls:
- *  Remove the driver for the specified property on the given ID block (if available)
+/**
+ * \brief Main Driver Management API calls.
+ *
+ * Remove the driver for the specified property on the given ID block (if available).
  */
 bool ANIM_remove_driver(
     struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 
 /* -------- */
 
-/* Clear copy-paste buffer for drivers */
+/**
+ * Clear copy-paste buffer for drivers.
+ * \note This function frees any MEM_calloc'ed copy/paste buffer data.
+ */
 void ANIM_drivers_copybuf_free(void);
 
-/* Clear copy-paste buffer for driver variable sets */
+/**
+ * Clear copy-paste buffer for driver variable sets.
+ * \note This function frees any MEM_calloc'ed copy/paste buffer data.
+ */
 void ANIM_driver_vars_copybuf_free(void);
 
 /* -------- */
 
-/* Returns whether there is a driver in the copy/paste buffer to paste */
+/**
+ * Returns whether there is a driver in the copy/paste buffer to paste.
+ */
 bool ANIM_driver_can_paste(void);
 
-/* Main Driver Management API calls:
- *  Make a copy of the driver for the specified property on the given ID block
+/**
+ * \brief Main Driver Management API calls.
+ *
+ * Make a copy of the driver for the specified property on the given ID block.
  */
 bool ANIM_copy_driver(
     struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 
-/* Main Driver Management API calls:
+/**
+ * \brief Main Driver Management API calls.
+ *
  * Add a new driver for the specified property on the given ID block or replace an existing one
- * with the driver + driver-curve data from the buffer
+ * with the driver + driver-curve data from the buffer.
  */
 bool ANIM_paste_driver(
     struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag);
 
 /* -------- */
 
-/* Checks if there are driver variables in the copy/paste buffer */
+/**
+ * Checks if there are driver variables in the copy/paste buffer.
+ */
 bool ANIM_driver_vars_can_paste(void);
 
-/* Copy the given driver's variables to the buffer */
+/**
+ * Copy the given driver's variables to the buffer.
+ */
 bool ANIM_driver_vars_copy(struct ReportList *reports, struct FCurve *fcu);
 
-/* Paste the variables in the buffer to the given FCurve */
+/**
+ * Paste the variables in the buffer to the given FCurve.
+ */
 bool ANIM_driver_vars_paste(struct ReportList *reports, struct FCurve *fcu, bool replace);
 
 /* -------- */
 
-/* Create a driver & variable that reads the specified property,
- * and store it in the buffers for Paste Driver and Paste Variables. */
+/**
+ * Create a driver & variable that reads the specified property,
+ * and store it in the buffers for Paste Driver and Paste Variables.
+ */
 void ANIM_copy_as_driver(struct ID *target_id, const char *target_path, const char *var_name);
 
-/* ************ Auto-Keyframing ********************** */
-/* Notes:
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Auto-Key-Framing
+ *
+ * Notes:
  * - All the defines for this (User-Pref settings and Per-Scene settings)
  *   are defined in DNA_userdef_types.h
- * - Scene settings take precedence over those for userprefs, with old files
- *   inheriting userpref settings for the scene settings
- * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored
- *   as userprefs
- */
+ * - Scene settings take precedence over those for user-preferences, with old files
+ *   inheriting user-preferences settings for the scene settings
+ * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored as user-preferences.
+ * \{ */
 
-/* Auto-Keying macros for use by various tools */
-/* check if auto-keyframing is enabled (per scene takes precedence) */
+/* Auto-Keying macros for use by various tools. */
+
+/** Check if auto-key-framing is enabled (per scene takes precedence).
+ */
 #define IS_AUTOKEY_ON(scene) \
   ((scene) ? ((scene)->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON))
-/* Check the mode for auto-keyframing (per scene takes precedence). */
+/** Check the mode for auto-keyframing (per scene takes precedence). */
 #define IS_AUTOKEY_MODE(scene, mode) \
   ((scene) ? ((scene)->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : \
              (U.autokey_mode == AUTOKEY_MODE_##mode))
-/* check if a flag is set for auto-keyframing (per scene takes precedence) */
+/** Check if a flag is set for auto-key-framing (per scene takes precedence). */
 #define IS_AUTOKEY_FLAG(scene, flag) \
   ((scene) ? (((scene)->toolsettings->autokey_flag & AUTOKEY_FLAG_##flag) || \
               (U.autokey_flag & AUTOKEY_FLAG_##flag)) : \
              (U.autokey_flag & AUTOKEY_FLAG_##flag))
 
-/* auto-keyframing feature - checks for whether anything should be done for the current frame */
+/**
+ * Auto-keyframing feature - checks for whether anything should be done for the current frame.
+ */
 bool autokeyframe_cfra_can_key(const struct Scene *scene, struct ID *id);
 
-/* ************ Keyframe Checking ******************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Keyframe Checking
+ * \{ */
 
-/* Lesser Keyframe Checking API call:
- * - Used for the buttons to check for keyframes...
+/**
+ * \brief Lesser Keyframe Checking API call.
+ *
+ * Checks if some F-Curve has a keyframe for a given frame.
+ * \note Used for the buttons to check for keyframes.
  */
 bool fcurve_frame_has_keyframe(const struct FCurve *fcu, float frame, short filter);
 
-/* Lesser Keyframe Checking API call:
+/**
+ * \brief Lesser Keyframe Checking API call.
+ *
  * - Returns whether the current value of a given property differs from the interpolated value.
  * - Used for button drawing.
  */
@@ -464,18 +627,19 @@ bool fcurve_is_changed(struct PointerRNA ptr,
                        const struct AnimationEvalContext *anim_eval_context);
 
 /**
- * Main Keyframe Checking API call:
+ * \brief Main Keyframe Checking API call.
+ *
  * Checks whether a keyframe exists for the given ID-block one the given frame.
- * - It is recommended to call this method over the other keyframe-checkers directly,
- *   in case some detail of the implementation changes...
- * - frame: the value of this is quite often result of #BKE_scene_ctime_get()
+ * It is recommended to call this method over the other keyframe-checkers directly,
+ * in case some detail of the implementation changes...
+ * \param frame: The value of this is quite often result of #BKE_scene_ctime_get()
  */
 bool id_frame_has_keyframe(struct ID *id, float frame, short filter);
 
-/* filter flags for id_cfra_has_keyframe
+/**
+ * Filter flags for #id_frame_has_keyframe.
  *
- * WARNING: do not alter order of these, as also stored in files
- * (for v3d->keyflags)
+ * \warning do not alter order of these, as also stored in files (for `v3d->keyflags`).
  */
 typedef enum eAnimFilterFlags {
   /* general */
@@ -488,7 +652,8 @@ typedef enum eAnimFilterFlags {
   ANIMFILTER_KEYS_NOSKEY = (1 << 10), /* don't include shape keys (for geometry) */
 } eAnimFilterFlags;
 
-/* utility funcs for auto keyframe */
+/* Utility functions for auto key-frame. */
+
 bool ED_autokeyframe_object(struct bContext *C,
                             struct Scene *scene,
                             struct Object *ob,
@@ -498,6 +663,9 @@ bool ED_autokeyframe_pchan(struct bContext *C,
                            struct Object *ob,
                            struct bPoseChannel *pchan,
                            struct KeyingSet *ks);
+/**
+ * Use for auto-key-framing from the UI.
+ */
 bool ED_autokeyframe_property(struct bContext *C,
                               struct Scene *scene,
                               PointerRNA *ptr,
@@ -506,7 +674,8 @@ bool ED_autokeyframe_property(struct bContext *C,
                               float cfra);
 
 /* Names for builtin keying sets so we don't confuse these with labels/text,
- * defined in python script: keyingsets_builtins.py */
+ * defined in python script: `keyingsets_builtins.py`. */
+
 #define ANIM_KS_LOCATION_ID "Location"
 #define ANIM_KS_ROTATION_ID "Rotation"
 #define ANIM_KS_SCALING_ID "Scaling"
@@ -516,6 +685,8 @@ bool ED_autokeyframe_property(struct bContext *C,
 #define ANIM_KS_WHOLE_CHARACTER_ID "WholeCharacter"
 #define ANIM_KS_WHOLE_CHARACTER_SELECTED_ID "WholeCharacterSelected"
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/editors/include/ED_markers.h b/source/blender/editors/include/ED_markers.h
index 8c10a8e36fd..8e6961ffd6f 100644
--- a/source/blender/editors/include/ED_markers.h
+++ b/source/blender/editors/include/ED_markers.h
@@ -33,7 +33,9 @@ struct bAnimContext;
 struct bContext;
 struct wmKeyConfig;
 
-/* Drawing API ------------------------------ */
+/* -------------------------------------------------------------------- */
+/** \name Drawing API
+ * \{ */
 
 /* flags for drawing markers */
 enum {
@@ -42,37 +44,86 @@ enum {
   DRAW_MARKERS_MARGIN = (1 << 2),
 };
 
+/* Draw Scene-Markers in time window */
 void ED_markers_draw(const struct bContext *C, int flag);
 
-/* Backend API ----------------------------- */
+/** \} */
 
+/* -------------------------------------------------------------------- */
+/** \name Backend API
+ * \{ */
+
+/**
+ * Public API for getting markers from context.
+ */
 ListBase *ED_context_get_markers(const struct bContext *C);
+/**
+ * Public API for getting markers from "animation" context.
+ */
 ListBase *ED_animcontext_get_markers(const struct bAnimContext *ac);
 
+/**
+ * Apply some transformation to markers after the fact
+ *
+ * \param markers: List of markers to affect - this may or may not be the scene markers list,
+ * so don't assume anything.
+ * \param scene: Current scene (for getting current frame)
+ * \param mode: (TfmMode) transform mode that this transform is for
+ * \param value: From the transform code, this is `t->vec[0]`
+ * (which is delta transform for grab/extend, and scale factor for scale)
+ * \param side: (B/L/R) for 'extend' functionality, which side of current frame to use
+ */
 int ED_markers_post_apply_transform(
     ListBase *markers, struct Scene *scene, int mode, float value, char side);
 
+/**
+ * Get the marker that is closest to this point.
+ * XXX: for select, the min_dist should be small.
+ */
 struct TimeMarker *ED_markers_find_nearest_marker(ListBase *markers, float x);
+/**
+ * Return the time of the marker that occurs on a frame closest to the given time.
+ */
 int ED_markers_find_nearest_marker_time(ListBase *markers, float x);
 
 void ED_markers_get_minmax(ListBase *markers, short sel, float *first, float *last);
 
+/**
+ * This function makes a list of all the markers. The only_sel
+ * argument is used to specify whether only the selected markers
+ * are added.
+ */
 void ED_markers_make_cfra_list(ListBase *markers, ListBase *lb, short sel);
 
 void ED_markers_deselect_all(ListBase *markers, int action);
 
+/**
+ * Get the first selected marker.
+ */
 struct TimeMarker *ED_markers_get_first_selected(ListBase *markers);
 
-/* Operators ------------------------------ */
+/** \} */
 
-/* called in screen_ops.c:ED_operatortypes_screen() */
+/* -------------------------------------------------------------------- */
+/** \name Operators
+ * \{ */
+
+/**
+ * Called in screen_ops.c:ED_operatortypes_screen().
+ */
 void ED_operatortypes_marker(void);
-/* called in screen_ops.c:ED_keymap_screen() */
+/**
+ * Called in screen_ops.c:ED_keymap_screen().
+ */
 void ED_keymap_marker(struct wmKeyConfig *keyconf);
 
-/* debugging only */
+/**
+ * Debugging only: print debugging prints of list of markers.
+ */
 void debug_markers_print_list(struct ListBase *markers);
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/editors/include/ED_screen.h b/source/blender/editors/include/ED_screen.h
index 76bbc899aba..c65ef3e397d 100644
--- a/source/blender/editors/include/ED_screen.h
+++ b/source/blender/editors/include/ED_screen.h
@@ -388,6 +388,10 @@ void ED_screens_navigation_bar_tools_menu_create(struct bContext *C,
  */
 bool ED_screen_stereo3d_required(const struct bScreen *screen, const struct Scene *scene);
 Scene *ED_screen_scene_find(const struct bScreen *screen, const struct wmWindowManager *wm);
+/**
+ * Find the scene displayed in \a screen.
+ * \note Assumes \a screen to be visible/active!
+ */
 Scene *ED_screen_scene_find_with_window(const struct bScreen *screen,
                                         const struct wmWindowManager *wm,
                                         struct wmWindow **r_window);
diff --git a/source/blender/editors/include/ED_view3d.h b/source/blender/editors/include/ED_view3d.h
index 16f84ddc3cc..11a8b11c35a 100644
--- a/source/blender/editors/include/ED_view3d.h
+++ b/source/blender/editors/include/ED_view3d.h
@@ -108,6 +108,8 @@ bool ED_view3d_has_workbench_in_texture_color(const struct Scene *scene,
                                               const struct Object *ob,
                                               const struct View3D *v3d);
 /**
+ * Cursor position in `r_cursor_co`, result in `r_cursor_co`, `mval` in region coords.
+ *
  * \note cannot use `event->mval` here, called by #object_add().
  */
 void ED_view3d_cursor3d_position(struct bContext *C,