Cleanup: anim, add some more documentation to the pose backup code

Just some more docs, to be clear about functionality and, most importantly,
pointer ownership.

No functional changes.

source/blender/blenkernel/BKE_pose_backup.h

@@ -21,10 +21,18 @@ extern "C" {
 struct PoseBackup;
 
 /**
- * Create a backup of those bones that are animated in the given action.
+ * Create a backup of those bones that are selected AND animated in the given action.
+ *
+ * The backup is owned by the caller, and should be freed with `BKE_pose_backup_free()`.
  */
 struct PoseBackup *BKE_pose_backup_create_selected_bones(
     const struct Object *ob, const struct bAction *action) ATTR_WARN_UNUSED_RESULT;
+
+/**
+ * Create a backup of those bones that are animated in the given action.
+ *
+ * The backup is owned by the caller, and should be freed with `BKE_pose_backup_free()`.
+ */
 struct PoseBackup *BKE_pose_backup_create_all_bones(
     const struct Object *ob, const struct bAction *action) ATTR_WARN_UNUSED_RESULT;
 bool BKE_pose_backup_is_selection_relevant(const struct PoseBackup *pose_backup);

source/blender/blenkernel/intern/pose_backup.cc

@@ -38,6 +38,14 @@ struct PoseBackup {
   ListBase /* PoseChannelBackup* */ backups;
 };
 
+/**
+ * Create a backup of the pose, for only those bones that are animated in the
+ * given Action. If `selected_bone_names` is not empty, the set of bones to back
+ * up is intersected with these bone names such that only the selected subset is
+ * backed up.
+ *
+ * The returned pointer is owned by the caller.
+ */
 static PoseBackup *pose_backup_create(const Object *ob,
                                       const bAction *action,
                                       const BoneNameSet &selected_bone_names)