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

Ref T92709

9 files changed, 175 insertions, 127 deletions

diff --git a/source/blender/windowmanager/gizmo/WM_gizmo_api.h b/source/blender/windowmanager/gizmo/WM_gizmo_api.h
index c7a4b064d0e..497e4f6e5fc 100644
--- a/source/blender/windowmanager/gizmo/WM_gizmo_api.h
+++ b/source/blender/windowmanager/gizmo/WM_gizmo_api.h
@@ -61,19 +61,42 @@ extern "C" {
 struct wmGizmo *WM_gizmo_new_ptr(const struct wmGizmoType *gzt,
                                  struct wmGizmoGroup *gzgroup,
                                  struct PointerRNA *properties);
+/**
+ * \param idname: Must be a valid gizmo type name,
+ * if you need to check it exists use #WM_gizmo_new_ptr
+ * because callers of this function don't NULL check the return value.
+ */
 struct wmGizmo *WM_gizmo_new(const char *idname,
                              struct wmGizmoGroup *gzgroup,
                              struct PointerRNA *properties);
+/**
+ * \warning this doesn't check #wmGizmoMap (highlight, selection etc).
+ * Typical use is when freeing the windowing data,
+ * where caller can manage clearing selection, highlight... etc.
+ */
 void WM_gizmo_free(struct wmGizmo *gz);
+/**
+ * Free \a gizmo and unlink from \a gizmolist.
+ * \a gizmolist is allowed to be NULL.
+ */
 void WM_gizmo_unlink(ListBase *gizmolist,
                      struct wmGizmoMap *gzmap,
                      struct wmGizmo *gz,
                      struct bContext *C);
 
+/**
+ * Remove from selection array without running callbacks.
+ */
 bool WM_gizmo_select_unlink(struct wmGizmoMap *gzmap, struct wmGizmo *gz);
 bool WM_gizmo_select_set(struct wmGizmoMap *gzmap, struct wmGizmo *gz, bool select);
 bool WM_gizmo_highlight_set(struct wmGizmoMap *gzmap, struct wmGizmo *gz);
 
+/**
+ * Special function to run from setup so gizmos start out interactive.
+ *
+ * We could do this when linking them,
+ * but this complicates things since the window update code needs to run first.
+ */
 void WM_gizmo_modal_set_from_setup(struct wmGizmoMap *gzmap,
                                    struct bContext *C,
                                    struct wmGizmo *gz,
@@ -87,17 +110,30 @@ struct PointerRNA *WM_gizmo_operator_set(struct wmGizmo *gz,
                                          struct IDProperty *properties);
 int WM_gizmo_operator_invoke(struct bContext *C, struct wmGizmo *gz, struct wmGizmoOpElem *gzop);
 
-/* callbacks */
+/* Callbacks. */
+
 void WM_gizmo_set_fn_custom_modal(struct wmGizmo *gz, wmGizmoFnModal fn);
 
 void WM_gizmo_set_matrix_location(struct wmGizmo *gz, const float origin[3]);
+/**
+ * #wmGizmo.matrix utility, set the orientation by it's Z axis.
+ */
 void WM_gizmo_set_matrix_rotation_from_z_axis(struct wmGizmo *gz, const float z_axis[3]);
+/**
+ * #wmGizmo.matrix utility, set the orientation by it's Y/Z axis.
+ */
 void WM_gizmo_set_matrix_rotation_from_yz_axis(struct wmGizmo *gz,
                                                const float y_axis[3],
                                                const float z_axis[3]);
 
 void WM_gizmo_set_matrix_offset_location(struct wmGizmo *gz, const float offset[3]);
+/**
+ * #wmGizmo.matrix_offset utility, set the orientation by it's Z axis.
+ */
 void WM_gizmo_set_matrix_offset_rotation_from_z_axis(struct wmGizmo *gz, const float z_axis[3]);
+/**
+ * #wmGizmo.matrix_offset utility, set the orientation by it's Y/Z axis.
+ */
 void WM_gizmo_set_matrix_offset_rotation_from_yz_axis(struct wmGizmo *gz,
                                                       const float y_axis[3],
                                                       const float z_axis[3]);
@@ -128,14 +164,30 @@ void WM_gizmo_calc_matrix_final_no_offset(const struct wmGizmo *gz, float r_mat[
 
 void WM_gizmo_calc_matrix_final(const struct wmGizmo *gz, float r_mat[4][4]);
 
-/* properties */
+/* Properties. */
+
 void WM_gizmo_properties_create_ptr(struct PointerRNA *ptr, struct wmGizmoType *gzt);
 void WM_gizmo_properties_create(struct PointerRNA *ptr, const char *gtstring);
+/**
+ * Similar to #WM_gizmo_properties_create
+ * except its uses ID properties used for key-maps and macros.
+ */
 void WM_gizmo_properties_alloc(struct PointerRNA **ptr,
                                struct IDProperty **properties,
                                const char *gtstring);
 void WM_gizmo_properties_sanitize(struct PointerRNA *ptr, const bool no_context);
+/**
+ * Set all props to their default.
+ *
+ * \param do_update: Only update un-initialized props.
+ *
+ * \note There's nothing specific to gizmos here.
+ * This could be made a general function.
+ */
 bool WM_gizmo_properties_default(struct PointerRNA *ptr, const bool do_update);
+/**
+ * Remove all props without #PROP_SKIP_SAVE.
+ */
 void WM_gizmo_properties_reset(struct wmGizmo *gz);
 void WM_gizmo_properties_clear(struct PointerRNA *ptr);
 void WM_gizmo_properties_free(struct PointerRNA *ptr);
@@ -146,7 +198,13 @@ void WM_gizmotype_append(void (*gtfunc)(struct wmGizmoType *));
 void WM_gizmotype_append_ptr(void (*gtfunc)(struct wmGizmoType *, void *), void *userdata);
 bool WM_gizmotype_remove(struct bContext *C, struct Main *bmain, const char *idname);
 void WM_gizmotype_remove_ptr(struct bContext *C, struct Main *bmain, struct wmGizmoType *gzt);
+/**
+ * Free but don't remove from ghash.
+ */
 void WM_gizmotype_free_ptr(struct wmGizmoType *gzt);
+/**
+ * Caller must free.
+ */
 void WM_gizmotype_iter(struct GHashIterator *ghi);
 
 /* wm_gizmo_group_type.c */
@@ -155,8 +213,15 @@ struct wmGizmoGroupType *WM_gizmogrouptype_append(void (*wtfunc)(struct wmGizmoG
 struct wmGizmoGroupType *WM_gizmogrouptype_append_ptr(void (*wtfunc)(struct wmGizmoGroupType *,
                                                                      void *),
                                                       void *userdata);
+/**
+ * Caller must free.
+ */
 void WM_gizmogrouptype_iter(struct GHashIterator *ghi);
 
+/**
+ * Append and insert into a gizmo typemap.
+ * This is most common for C gizmos which are enabled by default.
+ */
 struct wmGizmoGroupTypeRef *WM_gizmogrouptype_append_and_link(
     struct wmGizmoMapType *gzmap_type, void (*wtfunc)(struct wmGizmoGroupType *));
 
@@ -167,6 +232,10 @@ void WM_gizmoconfig_update_tag_group_type_init(struct wmGizmoMapType *gzmap_type
                                                struct wmGizmoGroupType *gzgt);
 void WM_gizmoconfig_update_tag_group_type_remove(struct wmGizmoMapType *gzmap_type,
                                                  struct wmGizmoGroupType *gzgt);
+/**
+ * Run in case new types have been added (runs often, early exit where possible).
+ * Follows #WM_keyconfig_update conventions.
+ */
 void WM_gizmoconfig_update(struct Main *bmain);
 
 void WM_gizmoconfig_update_tag_group_remove(struct wmGizmoMap *gzmap);
@@ -222,7 +291,8 @@ bool WM_gizmo_target_property_float_range_get(const struct wmGizmo *gz,
 int WM_gizmo_target_property_array_length(const struct wmGizmo *gz,
                                           struct wmGizmoProperty *gz_prop);
 
-/* definitions */
+/* Definitions. */
+
 const struct wmGizmoPropertyType *WM_gizmotype_target_property_find(const struct wmGizmoType *gzt,
                                                                     const char *idname);
 void WM_gizmotype_target_property_def(struct wmGizmoType *gzt,
@@ -230,14 +300,21 @@ void WM_gizmotype_target_property_def(struct wmGizmoType *gzt,
                                       int data_type,
                                       int array_length);
 
-/* utilities */
+/* Utilities. */
+
 void WM_gizmo_do_msg_notify_tag_refresh(struct bContext *C,
                                         struct wmMsgSubscribeKey *msg_key,
                                         struct wmMsgSubscribeValue *msg_val);
+/**
+ * Runs on the "prepare draw" pass, drawing the region clears.
+ */
 void WM_gizmo_target_property_subscribe_all(struct wmGizmo *gz,
                                             struct wmMsgBus *mbus,
                                             struct ARegion *region);
 
+/**
+ * Auto-key function if auto-key is enabled.
+ */
 void WM_gizmo_target_property_anim_autokey(struct bContext *C,
                                            const struct wmGizmo *gz,
                                            struct wmGizmoProperty *gz_prop);
@@ -256,6 +333,7 @@ struct wmKeyMap *WM_gizmogroup_setup_keymap_generic_maybe_drag(const struct wmGi
                                                                struct wmKeyConfig *kc);
 
 /* Utility functions (not callbacks). */
+
 struct wmKeyMap *WM_gizmo_keymap_generic_with_keyconfig(struct wmKeyConfig *kc);
 struct wmKeyMap *WM_gizmo_keymap_generic(struct wmWindowManager *wm);
 
@@ -268,19 +346,29 @@ struct wmKeyMap *WM_gizmo_keymap_generic_drag(struct wmWindowManager *wm);
 struct wmKeyMap *WM_gizmo_keymap_generic_click_drag_with_keyconfig(struct wmKeyConfig *kc);
 struct wmKeyMap *WM_gizmo_keymap_generic_click_drag(struct wmWindowManager *wm);
 
+/**
+ * Drag or press depending on preference.
+ */
 struct wmKeyMap *WM_gizmo_keymap_generic_maybe_drag_with_keyconfig(struct wmKeyConfig *kc);
 struct wmKeyMap *WM_gizmo_keymap_generic_maybe_drag(struct wmWindowManager *wm);
 
 void WM_gizmogroup_ensure_init(const struct bContext *C, struct wmGizmoGroup *gzgroup);
 
 /* Sort utilities for use with 'BLI_listbase_sort'. */
+
 int WM_gizmo_cmp_temp_fl(const void *gz_a_ptr, const void *gz_b_ptr);
 int WM_gizmo_cmp_temp_fl_reverse(const void *gz_a_ptr, const void *gz_b_ptr);
 
 /* -------------------------------------------------------------------- */
 /* wmGizmoMap */
 
+/**
+ * Creates a gizmo-map with all registered gizmos for that type
+ */
 struct wmGizmoMap *WM_gizmomap_new_from_type(const struct wmGizmoMapType_Params *gzmap_params);
+/**
+ * Re-create the gizmos (use when changing theme settings).
+ */
 void WM_gizmomap_reinit(struct wmGizmoMap *gzmap);
 const struct ListBase *WM_gizmomap_group_list(struct wmGizmoMap *gzmap);
 struct wmGizmoGroup *WM_gizmomap_group_find(struct wmGizmoMap *gzmap, const char *idname);
@@ -298,6 +386,12 @@ void WM_gizmomap_draw(struct wmGizmoMap *gzmap,
                       const struct bContext *C,
                       const eWM_GizmoFlagMapDrawStep drawstep);
 void WM_gizmomap_add_handlers(struct ARegion *region, struct wmGizmoMap *gzmap);
+/**
+ * Select/Deselect all selectable gizmos in \a gzmap.
+ * \return if selection has changed.
+ *
+ * TODO: select all by type.
+ */
 bool WM_gizmomap_select_all(struct bContext *C, struct wmGizmoMap *gzmap, const int action);
 bool WM_gizmomap_cursor_set(const struct wmGizmoMap *gzmap, struct wmWindow *win);
 void WM_gizmomap_message_subscribe(const struct bContext *C,
@@ -305,6 +399,9 @@ void WM_gizmomap_message_subscribe(const struct bContext *C,
                                    struct ARegion *region,
                                    struct wmMsgBus *mbus);
 bool WM_gizmomap_is_any_selected(const struct wmGizmoMap *gzmap);
+/**
+ * \note We could use a callback to define bounds, for now just use matrix location.
+ */
 bool WM_gizmomap_minmax(const struct wmGizmoMap *gzmap,
                         bool use_hidden,
                         bool use_select,
@@ -327,6 +424,10 @@ struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_find(struct wmGizmoMapType *gz
                                                        const char *idname);
 struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_find_ptr(struct wmGizmoMapType *gzmap_type,
                                                            const struct wmGizmoGroupType *gzgt);
+/**
+ * Use this for registering gizmos on startup.
+ * For runtime, use #WM_gizmomaptype_group_link_runtime.
+ */
 struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_link(struct wmGizmoMapType *gzmap_type,
                                                        const char *idname);
 struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_link_ptr(struct wmGizmoMapType *gzmap_type,
@@ -345,6 +446,9 @@ void WM_gizmomaptype_group_unlink(struct bContext *C,
                                   struct wmGizmoMapType *gzmap_type,
                                   const struct wmGizmoGroupType *gzgt);
 
+/**
+ * Unlike #WM_gizmomaptype_group_unlink this doesn't maintain correct state, simply free.
+ */
 void WM_gizmomaptype_group_free(struct wmGizmoGroupTypeRef *gzgt);
 
 /* -------------------------------------------------------------------- */
@@ -362,6 +466,9 @@ bool WM_gizmo_group_type_ensure_ptr_ex(struct wmGizmoGroupType *gzgt,
 bool WM_gizmo_group_type_ensure_ptr(struct wmGizmoGroupType *gzgt);
 bool WM_gizmo_group_type_ensure(const char *idname);
 
+/**
+ * Call #WM_gizmo_group_type_free_ptr after to remove & free.
+ */
 void WM_gizmo_group_type_remove_ptr_ex(struct Main *bmain,
                                        struct wmGizmoGroupType *gzgt,
                                        struct wmGizmoMapType *gzmap_type);
@@ -380,7 +487,9 @@ void WM_gizmo_group_unlink_delayed_ptr_from_space(struct wmGizmoGroupType *gzgt,
 void WM_gizmo_group_type_free_ptr(wmGizmoGroupType *gzgt);
 bool WM_gizmo_group_type_free(const char *idname);
 
-/* Has the result of unlinking and linking (re-initializes gizmo's). */
+/**
+ * Has the result of unlinking and linking (re-initializes gizmo's).
+ */
 void WM_gizmo_group_type_reinit_ptr_ex(struct Main *bmain,
                                        struct wmGizmoGroupType *gzgt,
                                        struct wmGizmoMapType *gzmap_type);
@@ -388,6 +497,7 @@ void WM_gizmo_group_type_reinit_ptr(struct Main *bmain, struct wmGizmoGroupType
 void WM_gizmo_group_type_reinit(struct Main *bmain, const char *idname);
 
 /* Utilities */
+
 bool WM_gizmo_context_check_drawstep(const struct bContext *C, eWM_GizmoFlagMapDrawStep step);
 
 void WM_gizmo_group_remove_by_tool(struct bContext *C,
@@ -398,6 +508,7 @@ void WM_gizmo_group_remove_by_tool(struct bContext *C,
 void WM_gizmo_group_tag_remove(struct wmGizmoGroup *gzgroup);
 
 /* Wrap Group Type Callbacks. */
+
 bool WM_gizmo_group_type_poll(const struct bContext *C, const struct wmGizmoGroupType *gzgt);
 void WM_gizmo_group_refresh(const struct bContext *C, struct wmGizmoGroup *gzgroup);
 
diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo.c
index cfedd67b2f0..d4f11c79d46 100644
--- a/source/blender/windowmanager/gizmo/intern/wm_gizmo.c
+++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo.c
@@ -106,11 +106,6 @@ wmGizmo *WM_gizmo_new_ptr(const wmGizmoType *gzt, wmGizmoGroup *gzgroup, Pointer
   return gz;
 }
 
-/**
- * \param idname: Must be a valid gizmo type name,
- * if you need to check it exists use #WM_gizmo_new_ptr
- * because callers of this function don't NULL check the return value.
- */
 wmGizmo *WM_gizmo_new(const char *idname, wmGizmoGroup *gzgroup, PointerRNA *properties)
 {
   const wmGizmoType *gzt = WM_gizmotype_find(idname, false);
@@ -143,11 +138,6 @@ static void wm_gizmo_register(wmGizmoGroup *gzgroup, wmGizmo *gz)
   wm_gizmogroup_gizmo_register(gzgroup, gz);
 }
 
-/**
- * \warning this doesn't check #wmGizmoMap (highlight, selection etc).
- * Typical use is when freeing the windowing data,
- * where caller can manage clearing selection, highlight... etc.
- */
 void WM_gizmo_free(wmGizmo *gz)
 {
   if (gz->type->free != NULL) {
@@ -187,10 +177,6 @@ void WM_gizmo_free(wmGizmo *gz)
   MEM_freeN(gz);
 }
 
-/**
- * Free \a gizmo and unlink from \a gizmolist.
- * \a gizmolist is allowed to be NULL.
- */
 void WM_gizmo_unlink(ListBase *gizmolist, wmGizmoMap *gzmap, wmGizmo *gz, bContext *C)
 {
   if (gz->state & WM_GIZMO_STATE_HIGHLIGHT) {
@@ -300,9 +286,6 @@ static void wm_gizmo_set_matrix_rotation_from_yz_axis__internal(float matrix[4][
   normalize_v3(matrix[0]);
 }
 
-/**
- * wmGizmo.matrix utils.
- */
 void WM_gizmo_set_matrix_rotation_from_z_axis(wmGizmo *gz, const float z_axis[3])
 {
   wm_gizmo_set_matrix_rotation_from_z_axis__internal(gz->matrix_basis, z_axis);
@@ -318,9 +301,6 @@ void WM_gizmo_set_matrix_location(wmGizmo *gz, const float origin[3])
   copy_v3_v3(gz->matrix_basis[3], origin);
 }
 
-/**
- * wmGizmo.matrix_offset utils.
- */
 void WM_gizmo_set_matrix_offset_rotation_from_z_axis(wmGizmo *gz, const float z_axis[3])
 {
   wm_gizmo_set_matrix_rotation_from_z_axis__internal(gz->matrix_offset, z_axis);
@@ -388,12 +368,7 @@ void WM_gizmo_set_fn_custom_modal(struct wmGizmo *gz, wmGizmoFnModal fn)
 /** \} */
 
 /* -------------------------------------------------------------------- */
-/**
- * Add/Remove \a gizmo to selection.
- * Reallocates memory for selected gizmos so better not call for selecting multiple ones.
- *
- * \return if the selection has changed.
- */
+
 bool wm_gizmo_select_set_ex(
     wmGizmoMap *gzmap, wmGizmo *gz, bool select, bool use_array, bool use_callback)
 {
@@ -429,7 +404,6 @@ bool wm_gizmo_select_set_ex(
   return changed;
 }
 
-/* Remove from selection array without running callbacks. */
 bool WM_gizmo_select_unlink(wmGizmoMap *gzmap, wmGizmo *gz)
 {
   return wm_gizmo_select_set_ex(gzmap, gz, false, true, false);
@@ -454,12 +428,6 @@ bool wm_gizmo_select_and_highlight(bContext *C, wmGizmoMap *gzmap, wmGizmo *gz)
   return false;
 }
 
-/**
- * Special function to run from setup so gizmos start out interactive.
- *
- * We could do this when linking them,
- * but this complicates things since the window update code needs to run first.
- */
 void WM_gizmo_modal_set_from_setup(struct wmGizmoMap *gzmap,
                                    struct bContext *C,
                                    struct wmGizmo *gz,
@@ -634,8 +602,6 @@ void WM_gizmo_properties_create(PointerRNA *ptr, const char *gtstring)
   }
 }
 
-/* similar to the function above except its uses ID properties
- * used for keymaps and macros */
 void WM_gizmo_properties_alloc(PointerRNA **ptr, IDProperty **properties, const char *gtstring)
 {
   if (*properties == NULL) {
@@ -680,14 +646,6 @@ void WM_gizmo_properties_sanitize(PointerRNA *ptr, const bool no_context)
   RNA_STRUCT_END;
 }
 
-/**
- * Set all props to their default.
- *
- * \param do_update: Only update un-initialized props.
- *
- * \note There's nothing specific to gizmos here.
- * This could be made a general function.
- */
 bool WM_gizmo_properties_default(PointerRNA *ptr, const bool do_update)
 {
   bool changed = false;
@@ -715,7 +673,6 @@ bool WM_gizmo_properties_default(PointerRNA *ptr, const bool do_update)
   return changed;
 }
 
-/* remove all props without PROP_SKIP_SAVE */
 void WM_gizmo_properties_reset(wmGizmo *gz)
 {
   if (gz->ptr->data) {
diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c
index b6d759eb95f..216bc260743 100644
--- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c
+++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group.c
@@ -63,9 +63,6 @@
 /** \name wmGizmoGroup
  * \{ */
 
-/**
- * Create a new gizmo-group from \a gzgt.
- */
 wmGizmoGroup *wm_gizmogroup_new_from_type(wmGizmoMap *gzmap, wmGizmoGroupType *gzgt)
 {
   wmGizmoGroup *gzgroup = MEM_callocN(sizeof(*gzgroup), "gizmo-group");
@@ -148,9 +145,6 @@ void WM_gizmo_group_tag_remove(wmGizmoGroup *gzgroup)
   }
 }
 
-/**
- * Add \a gizmo to \a gzgroup and make sure its name is unique within the group.
- */
 void wm_gizmogroup_gizmo_register(wmGizmoGroup *gzgroup, wmGizmo *gz)
 {
   BLI_assert(BLI_findindex(&gzgroup->gizmos, gz) == -1);
@@ -234,10 +228,6 @@ wmGizmo *wm_gizmogroup_find_intersected_gizmo(wmWindowManager *wm,
   return NULL;
 }
 
-/**
- * Adds all gizmos of \a gzgroup that can be selected to the head of \a listbase.
- * Added items need freeing!
- */
 void wm_gizmogroup_intersectable_gizmos_to_list(wmWindowManager *wm,
                                                 const wmGizmoGroup *gzgroup,
                                                 const int event_modifier,
@@ -821,7 +811,6 @@ struct wmKeyMap *WM_gizmo_keymap_generic_click_drag(wmWindowManager *wm)
   return WM_gizmo_keymap_generic_click_drag_with_keyconfig(wm->defaultconf);
 }
 
-/** Drag or press depending on preference. */
 struct wmKeyMap *WM_gizmo_keymap_generic_maybe_drag_with_keyconfig(wmKeyConfig *kc)
 {
   const char *idname = "Generic Gizmo Maybe Drag";
@@ -862,10 +851,6 @@ struct wmGizmoGroupTypeRef *WM_gizmomaptype_group_find(struct wmGizmoMapType *gz
   return NULL;
 }
 
-/**
- * Use this for registering gizmos on startup.
- * For runtime, use #WM_gizmomaptype_group_link_runtime.
- */
 wmGizmoGroupTypeRef *WM_gizmomaptype_group_link(wmGizmoMapType *gzmap_type, const char *idname)
 {
   wmGizmoGroupType *gzgt = WM_gizmogrouptype_find(idname, false);
@@ -939,9 +924,6 @@ wmGizmoGroup *WM_gizmomaptype_group_init_runtime_with_region(wmGizmoMapType *gzm
   return gzgroup;
 }
 
-/**
- * Unlike #WM_gizmomaptype_group_unlink this doesn't maintain correct state, simply free.
- */
 void WM_gizmomaptype_group_free(wmGizmoGroupTypeRef *gzgt_ref)
 {
   MEM_freeN(gzgt_ref);
@@ -1059,9 +1041,6 @@ bool WM_gizmo_group_type_ensure(const char *idname)
   return WM_gizmo_group_type_ensure_ptr(gzgt);
 }
 
-/**
- * Call #WM_gizmo_group_type_free_ptr after to remove & free.
- */
 void WM_gizmo_group_type_remove_ptr_ex(struct Main *bmain,
                                        wmGizmoGroupType *gzgt,
                                        wmGizmoMapType *gzmap_type)
diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c
index 6a793d52f74..0a36068bb21 100644
--- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c
+++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_group_type.c
@@ -71,7 +71,6 @@ wmGizmoGroupType *WM_gizmogrouptype_find(const char *idname, bool quiet)
   return NULL;
 }
 
-/* caller must free */
 void WM_gizmogrouptype_iter(GHashIterator *ghi)
 {
   BLI_ghashIterator_init(ghi, global_gizmogrouptype_hash);
@@ -127,10 +126,6 @@ wmGizmoGroupType *WM_gizmogrouptype_append_ptr(void (*wtfunc)(struct wmGizmoGrou
   return gzgt;
 }
 
-/**
- * Append and insert into a gizmo typemap.
- * This is most common for C gizmos which are enabled by default.
- */
 wmGizmoGroupTypeRef *WM_gizmogrouptype_append_and_link(wmGizmoMapType *gzmap_type,
                                                        void (*wtfunc)(struct wmGizmoGroupType *))
 {
@@ -190,7 +185,6 @@ void wm_gizmogrouptype_free(void)
   global_gizmogrouptype_hash = NULL;
 }
 
-/* called on initialize WM_init() */
 void wm_gizmogrouptype_init(void)
 {
   /* reserve size is set based on blender default setup */
diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h b/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h
index dd2db209771..b6912d79076 100644
--- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h
+++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_intern.h
@@ -29,6 +29,12 @@ struct wmKeyConfig;
 /* -------------------------------------------------------------------- */
 /* wmGizmo */
 
+/**
+ * Add/Remove \a gizmo to selection.
+ * Reallocates memory for selected gizmos so better not call for selecting multiple ones.
+ *
+ * \return if the selection has changed.
+ */
 bool wm_gizmo_select_set_ex(
     struct wmGizmoMap *gzmap, struct wmGizmo *gz, bool select, bool use_array, bool use_callback);
 bool wm_gizmo_select_and_highlight(bContext *C, struct wmGizmoMap *gzmap, struct wmGizmo *gz);
@@ -54,9 +60,15 @@ enum {
   TWEAK_MODAL_SNAP_OFF,
 };
 
+/**
+ * Create a new gizmo-group from \a gzgt.
+ */
 struct wmGizmoGroup *wm_gizmogroup_new_from_type(struct wmGizmoMap *gzmap,
                                                  struct wmGizmoGroupType *gzgt);
 void wm_gizmogroup_free(bContext *C, struct wmGizmoGroup *gzgroup);
+/**
+ * Add \a gizmo to \a gzgroup and make sure its name is unique within the group.
+ */
 void wm_gizmogroup_gizmo_register(struct wmGizmoGroup *gzgroup, struct wmGizmo *gz);
 struct wmGizmoGroup *wm_gizmogroup_find_by_type(const struct wmGizmoMap *gzmap,
                                                 const struct wmGizmoGroupType *gzgt);
@@ -66,6 +78,10 @@ struct wmGizmo *wm_gizmogroup_find_intersected_gizmo(wmWindowManager *wm,
                                                      const int event_modifier,
                                                      const int mval[2],
                                                      int *r_part);
+/**
+ * Adds all gizmos of \a gzgroup that can be selected to the head of \a listbase.
+ * Added items need freeing!
+ */
 void wm_gizmogroup_intersectable_gizmos_to_list(wmWindowManager *wm,
                                                 const struct wmGizmoGroup *gzgroup,
                                                 const int event_modifier,
@@ -137,6 +153,10 @@ struct wmGizmoMapType {
 };
 
 void wm_gizmomap_select_array_clear(struct wmGizmoMap *gzmap);
+/**
+ * Deselect all selected gizmos in \a gzmap.
+ * \return if selection has changed.
+ */
 bool wm_gizmomap_deselect_all(struct wmGizmoMap *gzmap);
 void wm_gizmomap_select_array_shrink(struct wmGizmoMap *gzmap, int len_subtract);
 void wm_gizmomap_select_array_push_back(struct wmGizmoMap *gzmap, wmGizmo *gz);
diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c
index 6f952bc9526..d3e682f1490 100644
--- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c
+++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_map.c
@@ -176,9 +176,6 @@ static wmGizmoMap *wm_gizmomap_new_from_type_ex(struct wmGizmoMapType *gzmap_typ
   return gzmap;
 }
 
-/**
- * Creates a gizmo-map with all registered gizmos for that type
- */
 wmGizmoMap *WM_gizmomap_new_from_type(const struct wmGizmoMapType_Params *gzmap_params)
 {
   wmGizmoMapType *gzmap_type = WM_gizmomaptype_ensure(gzmap_params);
@@ -207,7 +204,6 @@ void wm_gizmomap_remove(wmGizmoMap *gzmap)
   MEM_freeN(gzmap);
 }
 
-/** Re-create the gizmos (use when changing theme settings). */
 void WM_gizmomap_reinit(wmGizmoMap *gzmap)
 {
   wmGizmoMapType *gzmap_type = gzmap->type;
@@ -246,9 +242,6 @@ bool WM_gizmomap_is_any_selected(const wmGizmoMap *gzmap)
   return gzmap->gzmap_context.select.len != 0;
 }
 
-/**
- * \note We could use a callback to define bounds, for now just use matrix location.
- */
 bool WM_gizmomap_minmax(const wmGizmoMap *gzmap,
                         bool UNUSED(use_hidden),
                         bool use_select,
@@ -713,10 +706,6 @@ static wmGizmo *gizmo_find_intersected_3d(bContext *C,
   return result;
 }
 
-/**
- * Try to find a gizmo under the mouse position. 2D intersections have priority over
- * 3D ones (could check for smallest screen-space distance but not needed right now).
- */
 wmGizmo *wm_gizmomap_highlight_find(wmGizmoMap *gzmap,
                                     bContext *C,
                                     const wmEvent *event,
@@ -843,10 +832,6 @@ void wm_gizmomaps_handled_modal_update(bContext *C, wmEvent *event, wmEventHandl
   CTX_wm_region_set(C, region);
 }
 
-/**
- * Deselect all selected gizmos in \a gzmap.
- * \return if selection has changed.
- */
 bool wm_gizmomap_deselect_all(wmGizmoMap *gzmap)
 {
   wmGizmoMapSelectState *msel = &gzmap->gzmap_context.select;
@@ -903,12 +888,6 @@ static bool wm_gizmomap_select_all_intern(bContext *C, wmGizmoMap *gzmap)
   return changed;
 }
 
-/**
- * Select/Deselect all selectable gizmos in \a gzmap.
- * \return if selection has changed.
- *
- * TODO: select all by type.
- */
 bool WM_gizmomap_select_all(bContext *C, wmGizmoMap *gzmap, const int action)
 {
   bool changed = false;
@@ -932,10 +911,6 @@ bool WM_gizmomap_select_all(bContext *C, wmGizmoMap *gzmap, const int action)
   return changed;
 }
 
-/**
- * Prepare context for gizmo handling (but only if area/region is
- * part of screen). Version of #wm_handler_op_context for gizmos.
- */
 void wm_gizmomap_handler_context_op(bContext *C, wmEventHandler_Op *handler)
 {
   bScreen *screen = CTX_wm_screen(C);
@@ -1037,9 +1012,6 @@ wmGizmo *wm_gizmomap_highlight_get(wmGizmoMap *gzmap)
   return gzmap->gzmap_context.highlight;
 }
 
-/**
- * Caller should call exit when (enable == False).
- */
 void wm_gizmomap_modal_set(
     wmGizmoMap *gzmap, bContext *C, wmGizmo *gz, const wmEvent *event, bool enable)
 {
@@ -1247,9 +1219,6 @@ void wm_gizmomaptypes_free(void)
   }
 }
 
-/**
- * Initialize keymaps for all existing gizmo-groups
- */
 void wm_gizmos_keymap(wmKeyConfig *keyconf)
 {
   LISTBASE_FOREACH (wmGizmoMapType *, gzmap_type, &gizmomaptypes) {
@@ -1293,10 +1262,6 @@ void WM_gizmoconfig_update_tag_group_remove(wmGizmoMap *gzmap)
   wm_gzmap_type_update_flag |= WM_GIZMOTYPE_GLOBAL_UPDATE_REMOVE;
 }
 
-/**
- * Run in case new types have been added (runs often, early exit where possible).
- * Follows #WM_keyconfig_update conventions.
- */
 void WM_gizmoconfig_update(struct Main *bmain)
 {
   if (G.background) {
diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c
index 63e833d73c3..57555fb5416 100644
--- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c
+++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_target_props.c
@@ -319,10 +319,6 @@ void WM_gizmo_do_msg_notify_tag_refresh(bContext *UNUSED(C),
   WM_gizmomap_tag_refresh(gzmap);
 }
 
-/**
- * Runs on the "prepare draw" pass,
- * drawing the region clears.
- */
 void WM_gizmo_target_property_subscribe_all(wmGizmo *gz, struct wmMsgBus *mbus, ARegion *region)
 {
   if (gz->type->target_property_defs_len) {
@@ -355,9 +351,6 @@ void WM_gizmo_target_property_subscribe_all(wmGizmo *gz, struct wmMsgBus *mbus,
   }
 }
 
-/**
- * Auto-key function if auto-key is enabled.
- */
 void WM_gizmo_target_property_anim_autokey(bContext *C,
                                            const wmGizmo *UNUSED(gz),
                                            wmGizmoProperty *gz_prop)
diff --git a/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c b/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c
index 1523246d08b..602100a624e 100644
--- a/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c
+++ b/source/blender/windowmanager/gizmo/intern/wm_gizmo_type.c
@@ -78,7 +78,6 @@ const wmGizmoType *WM_gizmotype_find(const char *idname, bool quiet)
   return NULL;
 }
 
-/* caller must free */
 void WM_gizmotype_iter(GHashIterator *ghi)
 {
   BLI_ghashIterator_init(ghi, global_gizmotype_hash);
@@ -118,9 +117,6 @@ void WM_gizmotype_append_ptr(void (*gtfunc)(struct wmGizmoType *, void *), void
   wm_gizmotype_append__end(mt);
 }
 
-/**
- * Free but don't remove from ghash.
- */
 void WM_gizmotype_free_ptr(wmGizmoType *gzt)
 {
   if (gzt->rna_ext.srna) { /* python gizmo, allocs own string */
@@ -195,7 +191,6 @@ void wm_gizmotype_free(void)
   global_gizmotype_hash = NULL;
 }
 
-/* called on initialize WM_init() */
 void wm_gizmotype_init(void)
 {
   /* reserve size is set based on blender default setup */
diff --git a/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h b/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h
index 18b3f40aba6..0612ba97db0 100644
--- a/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h
+++ b/source/blender/windowmanager/gizmo/wm_gizmo_wmapi.h
@@ -40,37 +40,63 @@ extern "C" {
 #endif
 
 /* -------------------------------------------------------------------- */
-/* wmGizmo */
+/** \name #wmGizmo
+ * \{ */
 
 /* wm_gizmo_type.c, for init/exit */
+
 void wm_gizmotype_free(void);
+/**
+ * Called on initialize #WM_init().
+ */
 void wm_gizmotype_init(void);
 
 /* wm_gizmogroup_type.c, for init/exit */
+
 void wm_gizmogrouptype_free(void);
+/**
+ * Called on initialize #WM_init().
+ */
 void wm_gizmogrouptype_init(void);
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
-/* wmGizmoGroup */
+/** \name #wmGizmoGroup
+ * \{ */
 
 void GIZMOGROUP_OT_gizmo_select(struct wmOperatorType *ot);
 void GIZMOGROUP_OT_gizmo_tweak(struct wmOperatorType *ot);
 
 bool wm_gizmogroup_is_any_selected(const struct wmGizmoGroup *gzgroup);
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
-/* wmGizmoMap */
+/** \name #wmGizmoMap
+ * \{ */
 
 void wm_gizmomap_remove(struct wmGizmoMap *gzmap);
 
+/**
+ * Initialize key-maps for all existing gizmo-groups
+ */
 void wm_gizmos_keymap(struct wmKeyConfig *keyconf);
 
 void wm_gizmomaps_handled_modal_update(bContext *C,
                                        struct wmEvent *event,
                                        struct wmEventHandler_Op *handler);
+/**
+ * Prepare context for gizmo handling (but only if area/region is
+ * part of screen). Version of #wm_handler_op_context for gizmos.
+ */
 void wm_gizmomap_handler_context_op(bContext *C, struct wmEventHandler_Op *handler);
 void wm_gizmomap_handler_context_gizmo(bContext *C, struct wmEventHandler_Gizmo *handler);
 
+/**
+ * Try to find a gizmo under the mouse position. 2D intersections have priority over
+ * 3D ones (could check for smallest screen-space distance but not needed right now).
+ */
 struct wmGizmo *wm_gizmomap_highlight_find(struct wmGizmoMap *gzmap,
                                            bContext *C,
                                            const struct wmEvent *event,
@@ -80,6 +106,9 @@ bool wm_gizmomap_highlight_set(struct wmGizmoMap *gzmap,
                                struct wmGizmo *gz,
                                int part);
 struct wmGizmo *wm_gizmomap_highlight_get(struct wmGizmoMap *gzmap);
+/**
+ * Caller should call exit when (enable == False).
+ */
 void wm_gizmomap_modal_set(struct wmGizmoMap *gzmap,
                            bContext *C,
                            struct wmGizmo *gz,
@@ -90,11 +119,16 @@ struct wmGizmo *wm_gizmomap_modal_get(struct wmGizmoMap *gzmap);
 struct wmGizmo **wm_gizmomap_selected_get(wmGizmoMap *gzmap, int *r_selected_len);
 struct ListBase *wm_gizmomap_groups_get(wmGizmoMap *gzmap);
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
-/* wmGizmoMapType */
+/** \name #wmGizmoMapType
+ * \{ */
 
 void wm_gizmomaptypes_free(void);
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif