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

Ref T92709

10 files changed, 32 insertions, 259 deletions

diff --git a/source/blender/makesrna/intern/rna_access.c b/source/blender/makesrna/intern/rna_access.c
index 40b5f3ed1da..ab9568aa3de 100644
--- a/source/blender/makesrna/intern/rna_access.c
+++ b/source/blender/makesrna/intern/rna_access.c
@@ -438,12 +438,6 @@ static PropertyRNA *arraytypemap[IDP_NUMTYPES] = {
     (PropertyRNA *)&rna_PropertyGroupItem_double_array,
 };
 
-/* This function initializes a PropertyRNAOrID with all required info, from a given PropertyRNA
- * and PointerRNA data. It deals properly with the three cases (static RNA, runtime RNA, and
- * IDProperty).
- * WARNING: given `ptr` PointerRNA is assumed to be a valid data one here, calling code is
- * responsible to ensure that.
- */
 void rna_property_rna_or_id_get(PropertyRNA *prop,
                                 PointerRNA *ptr,
                                 PropertyRNAOrID *r_prop_rna_or_id)
@@ -515,8 +509,6 @@ void rna_property_rna_or_id_get(PropertyRNA *prop,
   }
 }
 
-/* This function only returns an IDProperty,
- * or NULL (in case IDProp could not be found, or prop is a real RNA property). */
 IDProperty *rna_idproperty_check(PropertyRNA **prop, PointerRNA *ptr)
 {
   PropertyRNAOrID prop_rna_or_id;
@@ -527,8 +519,6 @@ IDProperty *rna_idproperty_check(PropertyRNA **prop, PointerRNA *ptr)
   return prop_rna_or_id.idprop;
 }
 
-/* This function always return the valid, real data pointer, be it a regular RNA property one,
- * or an IDProperty one. */
 PropertyRNA *rna_ensure_property_realdata(PropertyRNA **prop, PointerRNA *ptr)
 {
   PropertyRNAOrID prop_rna_or_id;
@@ -661,11 +651,6 @@ StructRNA *RNA_struct_base(StructRNA *type)
   return type->base;
 }
 
-/**
- * Use to find the subtype directly below a base-type.
- *
- * So if type were `RNA_SpotLIght`, `RNA_struct_base_of(type, &RNA_ID)` would return `&RNA_Light`.
- */
 const StructRNA *RNA_struct_base_child_of(const StructRNA *type, const StructRNA *parent_type)
 {
   while (type) {
@@ -697,18 +682,11 @@ bool RNA_struct_idprops_datablock_allowed(const StructRNA *type)
   return (type->flag & (STRUCT_NO_DATABLOCK_IDPROPERTIES | STRUCT_NO_IDPROPERTIES)) == 0;
 }
 
-/**
- * Whether given type implies datablock usage by IDProperties.
- * This is used to prevent classes allowed to have IDProperties,
- * but not datablock ones, to indirectly use some
- * (e.g. by assigning an IDP_GROUP containing some IDP_ID pointers...).
- */
 bool RNA_struct_idprops_contains_datablock(const StructRNA *type)
 {
   return (type->flag & (STRUCT_CONTAINS_DATABLOCK_IDPROPERTIES | STRUCT_ID)) != 0;
 }
 
-/* remove an id-property */
 bool RNA_struct_idprops_unset(PointerRNA *ptr, const char *identifier)
 {
   IDProperty *group = RNA_struct_idprops(ptr, 0);
@@ -825,8 +803,6 @@ unsigned int RNA_struct_count_properties(StructRNA *srna)
   return counter;
 }
 
-/* Low level direct access to type->properties,
- * note this ignores parent classes so should be used with care. */
 const struct ListBase *RNA_struct_type_properties(StructRNA *srna)
 {
   return &srna->cont.properties;
@@ -837,10 +813,6 @@ PropertyRNA *RNA_struct_type_find_property_no_base(StructRNA *srna, const char *
   return BLI_findstring_ptr(&srna->cont.properties, identifier, offsetof(PropertyRNA, identifier));
 }
 
-/**
- * \note #RNA_struct_find_property is a higher level alternative to this function
- * which takes a #PointerRNA instead of a #StructRNA.
- */
 PropertyRNA *RNA_struct_type_find_property(StructRNA *srna, const char *identifier)
 {
   for (; srna; srna = srna->base) {
@@ -953,9 +925,6 @@ char *RNA_struct_name_get_alloc(PointerRNA *ptr, char *fixedbuf, int fixedlen, i
   return NULL;
 }
 
-/**
- * Use when registering structs with the #STRUCT_PUBLIC_NAMESPACE flag.
- */
 bool RNA_struct_available_or_report(ReportList *reports, const char *identifier)
 {
   const StructRNA *srna_exists = RNA_struct_find(identifier);
@@ -1098,12 +1067,6 @@ int RNA_property_flag(PropertyRNA *prop)
   return rna_ensure_property(prop)->flag;
 }
 
-/**
- * Get the tags set for \a prop as int bitfield.
- * \note Doesn't perform any validity check on the set bits. #RNA_def_property_tags does this
- *       in debug builds (to avoid performance issues in non-debug builds), which should be
- *       the only way to set tags. Hence, at this point we assume the tag bitfield to be valid.
- */
 int RNA_property_tags(PropertyRNA *prop)
 {
   return rna_ensure_property(prop)->tags;
@@ -1129,7 +1092,6 @@ bool RNA_property_array_check(PropertyRNA *prop)
   return rna_ensure_property_array_check(prop);
 }
 
-/* used by BPY to make an array from the python object */
 int RNA_property_array_dimension(PointerRNA *ptr, PropertyRNA *prop, int length[])
 {
   PropertyRNA *rprop = rna_ensure_property(prop);
@@ -1141,7 +1103,6 @@ int RNA_property_array_dimension(PointerRNA *ptr, PropertyRNA *prop, int length[
   return rprop->arraydimension;
 }
 
-/* Return the size of Nth dimension. */
 int RNA_property_multi_array_length(PointerRNA *ptr, PropertyRNA *prop, int dim)
 {
   int len[RNA_MAX_ARRAY_DIMENSION];
@@ -1445,9 +1406,6 @@ int RNA_property_int_clamp(PointerRNA *ptr, PropertyRNA *prop, int *value)
   return 0;
 }
 
-/**
- * \return the maximum length including the \0 terminator. '0' is used when there is no maximum.
- */
 int RNA_property_string_maxlength(PropertyRNA *prop)
 {
   StringPropertyRNA *sprop = (StringPropertyRNA *)rna_ensure_property(prop);
@@ -1774,10 +1732,6 @@ int RNA_enum_from_identifier(const EnumPropertyItem *item, const char *identifie
   return -1;
 }
 
-/**
- * Take care using this with translated enums,
- * prefer #RNA_enum_from_identifier where possible.
- */
 int RNA_enum_from_name(const EnumPropertyItem *item, const char *name)
 {
   int i = 0;
@@ -1973,10 +1927,6 @@ bool RNA_property_editable(PointerRNA *ptr, PropertyRNA *prop_orig)
                (!ID_IS_OVERRIDE_LIBRARY(id) || RNA_property_overridable_get(ptr, prop_orig)))));
 }
 
-/**
- * Version of #RNA_property_editable that tries to return additional info in \a r_info
- * that can be exposed in UI.
- */
 bool RNA_property_editable_info(PointerRNA *ptr, PropertyRNA *prop, const char **r_info)
 {
   ID *id = ptr->owner_id;
@@ -2027,7 +1977,6 @@ bool RNA_property_editable_flag(PointerRNA *ptr, PropertyRNA *prop)
   return (flag & PROP_EDITABLE) != 0;
 }
 
-/* same as RNA_property_editable(), except this checks individual items in an array */
 bool RNA_property_editable_index(PointerRNA *ptr, PropertyRNA *prop, int index)
 {
   ID *id;
@@ -2090,8 +2039,6 @@ bool RNA_property_animated(PointerRNA *ptr, PropertyRNA *prop)
 
   return false;
 }
-/* this function is to check if its possible to create a valid path from the ID
- * its slow so don't call in a loop */
 bool RNA_property_path_from_ID_check(PointerRNA *ptr, PropertyRNA *prop)
 {
   char *path = RNA_path_from_ID_to_property(ptr, prop);
@@ -2194,11 +2141,9 @@ static void rna_property_update(
   }
 }
 
-/* must keep in sync with 'rna_property_update'
- * NOTE: its possible this returns a false positive in the case of #PROP_CONTEXT_UPDATE
- * but this isn't likely to be a performance problem. */
 bool RNA_property_update_check(PropertyRNA *prop)
 {
+  /* NOTE: must keep in sync with #rna_property_update. */
   return (prop->magic != RNA_MAGIC || prop->update || prop->noteflag);
 }
 
@@ -2207,7 +2152,6 @@ void RNA_property_update(bContext *C, PointerRNA *ptr, PropertyRNA *prop)
   rna_property_update(C, CTX_data_main(C), CTX_data_scene(C), ptr, prop);
 }
 
-/* NOTE: `scene` pointer may be NULL. */
 void RNA_property_update_main(Main *bmain, Scene *scene, PointerRNA *ptr, PropertyRNA *prop)
 {
   rna_property_update(NULL, bmain, scene, ptr, prop);
@@ -3277,7 +3221,6 @@ char *RNA_property_string_get_alloc(
   return buf;
 }
 
-/* this is the length without \0 terminator */
 int RNA_property_string_length(PointerRNA *ptr, PropertyRNA *prop)
 {
   StringPropertyRNA *sprop = (StringPropertyRNA *)prop;
@@ -3417,7 +3360,6 @@ char *RNA_property_string_get_default_alloc(
   return buf;
 }
 
-/* this is the length without \0 terminator */
 int RNA_property_string_default_length(PointerRNA *UNUSED(ptr), PropertyRNA *prop)
 {
   StringPropertyRNA *sprop = (StringPropertyRNA *)rna_ensure_property(prop);
@@ -3498,13 +3440,6 @@ int RNA_property_enum_get_default(PointerRNA *UNUSED(ptr), PropertyRNA *prop)
   return eprop->defaultvalue;
 }
 
-/**
- * Get the value of the item that is \a step items away from \a from_value.
- *
- * \param from_value: Item value to start stepping from.
- * \param step: Absolute value defines step size, sign defines direction.
- *              E.g to get the next item, pass 1, for the previous -1.
- */
 int RNA_property_enum_step(
     const bContext *C, PointerRNA *ptr, PropertyRNA *prop, int from_value, int step)
 {
@@ -4212,7 +4147,6 @@ int RNA_property_collection_lookup_string(PointerRNA *ptr,
   return RNA_property_collection_lookup_string_index(ptr, prop, key, r_ptr, &index);
 }
 
-/* zero return is an assignment error */
 int RNA_property_collection_assign_int(PointerRNA *ptr,
                                        PropertyRNA *prop,
                                        const int key,
@@ -5326,17 +5260,6 @@ static bool rna_path_parse(PointerRNA *ptr,
   return true;
 }
 
-/**
- * Resolve the given RNA Path to find the pointer and/or property
- * indicated by fully resolving the path.
- *
- * \warning Unlike \a RNA_path_resolve_property(), that one *will* try to follow RNAPointers,
- * e.g. the path 'parent' applied to a RNAObject \a ptr will return the object.parent in \a r_ptr,
- * and a NULL \a r_prop...
- *
- * \note Assumes all pointers provided are valid
- * \return True if path can be resolved to a valid "pointer + property" OR "pointer only"
- */
 bool RNA_path_resolve(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop)
 {
   if (!rna_path_parse(ptr, path, r_ptr, r_prop, NULL, NULL, NULL, true)) {
@@ -5346,13 +5269,6 @@ bool RNA_path_resolve(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, Prop
   return r_ptr->data != NULL;
 }
 
-/**
- * Resolve the given RNA Path to find the pointer and/or property + array index
- * indicated by fully resolving the path.
- *
- * \note Assumes all pointers provided are valid.
- * \return True if path can be resolved to a valid "pointer + property" OR "pointer only"
- */
 bool RNA_path_resolve_full(
     PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index)
 {
@@ -5363,26 +5279,12 @@ bool RNA_path_resolve_full(
   return r_ptr->data != NULL;
 }
 
-/**
- * A version of #RNA_path_resolve_full doesn't check the value of #PointerRNA.data.
- *
- * \note While it's correct to ignore the value of #PointerRNA.data
- * most callers need to know if the resulting pointer was found and not null.
- */
 bool RNA_path_resolve_full_maybe_null(
     PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index)
 {
   return rna_path_parse(ptr, path, r_ptr, r_prop, r_index, NULL, NULL, true);
 }
 
-/**
- * Resolve the given RNA Path to find both the pointer AND property
- * indicated by fully resolving the path.
- *
- * This is a convenience method to avoid logic errors and ugly syntax.
- * \note Assumes all pointers provided are valid
- * \return True only if both a valid pointer and property are found after resolving the path
- */
 bool RNA_path_resolve_property(PointerRNA *ptr,
                                const char *path,
                                PointerRNA *r_ptr,
@@ -5395,14 +5297,6 @@ bool RNA_path_resolve_property(PointerRNA *ptr,
   return r_ptr->data != NULL && *r_prop != NULL;
 }
 
-/**
- * Resolve the given RNA Path to find the pointer AND property (as well as the array index)
- * indicated by fully resolving the path.
- *
- * This is a convenience method to avoid logic errors and ugly syntax.
- * \note Assumes all pointers provided are valid
- * \return True only if both a valid pointer and property are found after resolving the path
- */
 bool RNA_path_resolve_property_full(
     PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop, int *r_index)
 {
@@ -5413,18 +5307,6 @@ bool RNA_path_resolve_property_full(
   return r_ptr->data != NULL && *r_prop != NULL;
 }
 
-/**
- * Resolve the given RNA Path to find both the pointer AND property
- * indicated by fully resolving the path, and get the value of the Pointer property
- * (or item of the collection).
- *
- * This is a convenience method to avoid logic errors and ugly syntax,
- * it combines both \a RNA_path_resolve and #RNA_path_resolve_property in a single call.
- * \note Assumes all pointers provided are valid.
- * \param r_item_ptr: The final Pointer or Collection item value.
- * You must check for its validity before use!
- * \return True only if both a valid pointer and property are found after resolving the path
- */
 bool RNA_path_resolve_property_and_item_pointer(PointerRNA *ptr,
                                                 const char *path,
                                                 PointerRNA *r_ptr,
@@ -5438,19 +5320,6 @@ bool RNA_path_resolve_property_and_item_pointer(PointerRNA *ptr,
   return r_ptr->data != NULL && *r_prop != NULL;
 }
 
-/**
- * Resolve the given RNA Path to find both the pointer AND property (as well as the array index)
- * indicated by fully resolving the path,
- * and get the value of the Pointer property (or item of the collection).
- *
- * This is a convenience method to avoid logic errors and ugly syntax,
- * it combines both \a RNA_path_resolve_full and
- * \a RNA_path_resolve_property_full in a single call.
- * \note Assumes all pointers provided are valid.
- * \param r_item_ptr: The final Pointer or Collection item value.
- * You must check for its validity before use!
- * \return True only if both a valid pointer and property are found after resolving the path
- */
 bool RNA_path_resolve_property_and_item_pointer_full(PointerRNA *ptr,
                                                      const char *path,
                                                      PointerRNA *r_ptr,
@@ -5464,15 +5333,6 @@ bool RNA_path_resolve_property_and_item_pointer_full(PointerRNA *ptr,
 
   return r_ptr->data != NULL && *r_prop != NULL;
 }
-/**
- * Resolve the given RNA Path into a linked list of PropertyElemRNA's.
- *
- * To be used when complex operations over path are needed, like e.g. get relative paths,
- * to avoid too much string operations.
- *
- * \return True if there was no error while resolving the path
- * \note Assumes all pointers provided are valid
- */
 bool RNA_path_resolve_elements(PointerRNA *ptr, const char *path, ListBase *r_elements)
 {
   return rna_path_parse(ptr, path, NULL, NULL, NULL, NULL, r_elements, false);
@@ -5723,16 +5583,6 @@ static char *rna_idp_path(PointerRNA *ptr,
   return path;
 }
 
-/**
- * Find the path from the structure referenced by the pointer to the runtime RNA-defined
- * #IDProperty object.
- *
- * \note Does *not* handle pure user-defined IDProperties (a.k.a. custom properties).
- *
- * \param ptr: Reference to the object owning the custom property storage.
- * \param needle: Custom property object to find.
- * \return Relative path or NULL.
- */
 char *RNA_path_from_struct_to_idproperty(PointerRNA *ptr, IDProperty *needle)
 {
   IDProperty *haystack = RNA_struct_idprops(ptr, false);
@@ -5759,13 +5609,6 @@ static char *rna_path_from_ID_to_idpgroup(const PointerRNA *ptr)
   return RNA_path_from_struct_to_idproperty(&id_ptr, ptr->data);
 }
 
-/**
- * Find the actual ID pointer and path from it to the given ID.
- *
- * \param id: ID reference to search the global owner for.
- * \param[out] r_path: Path from the real ID to the initial ID.
- * \return The ID pointer, or NULL in case of failure.
- */
 ID *RNA_find_real_ID_and_path(Main *bmain, ID *id, const char **r_path)
 {
   if (r_path) {
@@ -5918,11 +5761,6 @@ static void rna_path_array_multi_string_from_flat_index(PointerRNA *ptr,
   }
 }
 
-/**
- * \param index_dim: The dimension to show, 0 disables. 1 for 1d array, 2 for 2d. etc.
- * \param index: The *flattened* index to use when \a `index_dim > 0`,
- * this is expanded when used with multi-dimensional arrays.
- */
 char *RNA_path_from_ID_to_property_index(PointerRNA *ptr,
                                          PropertyRNA *prop,
                                          int index_dim,
@@ -5994,10 +5832,6 @@ char *RNA_path_from_real_ID_to_property_index(
   return path != NULL ? rna_prepend_real_ID_path(bmain, ptr->owner_id, path, r_real_id) : NULL;
 }
 
-/**
- * \return the path to given ptr/prop from the closest ancestor of given type,
- * if any (else return NULL).
- */
 char *RNA_path_resolve_from_type_to_property(PointerRNA *ptr,
                                              PropertyRNA *prop,
                                              const StructRNA *type)
@@ -6036,10 +5870,6 @@ char *RNA_path_resolve_from_type_to_property(PointerRNA *ptr,
   return path;
 }
 
-/**
- * Get the ID as a python representation, eg:
- *   bpy.data.foo["bar"]
- */
 char *RNA_path_full_ID_py(Main *bmain, ID *id)
 {
   const char *path;
@@ -6075,10 +5905,6 @@ char *RNA_path_full_ID_py(Main *bmain, ID *id)
                       path);
 }
 
-/**
- * Get the ID.struct as a python representation, eg:
- *   bpy.data.foo["bar"].some_struct
- */
 char *RNA_path_full_struct_py(Main *bmain, struct PointerRNA *ptr)
 {
   char *id_path;
@@ -6107,10 +5933,6 @@ char *RNA_path_full_struct_py(Main *bmain, struct PointerRNA *ptr)
   return ret;
 }
 
-/**
- * Get the ID.struct.property as a python representation, eg:
- *   bpy.data.foo["bar"].some_struct.some_prop[10]
- */
 char *RNA_path_full_property_py_ex(
     Main *bmain, PointerRNA *ptr, PropertyRNA *prop, int index, bool use_fallback)
 {
@@ -6164,10 +5986,6 @@ char *RNA_path_full_property_py(Main *bmain, PointerRNA *ptr, PropertyRNA *prop,
   return RNA_path_full_property_py_ex(bmain, ptr, prop, index, false);
 }
 
-/**
- * Get the struct.property as a python representation, eg:
- *   some_struct.some_prop[10]
- */
 char *RNA_path_struct_property_py(PointerRNA *ptr, PropertyRNA *prop, int index)
 {
   char *data_path;
@@ -6205,10 +6023,6 @@ char *RNA_path_struct_property_py(PointerRNA *ptr, PropertyRNA *prop, int index)
   return ret;
 }
 
-/**
- * Get the struct.property as a python representation, eg:
- *   some_prop[10]
- */
 char *RNA_path_property_py(const PointerRNA *UNUSED(ptr), PropertyRNA *prop, int index)
 {
   char *ret;
@@ -6678,7 +6492,6 @@ bool RNA_property_is_idprop(const PropertyRNA *prop)
   return (prop->magic != RNA_MAGIC);
 }
 
-/* mainly for the UI */
 bool RNA_property_is_unlink(PropertyRNA *prop)
 {
   const int flag = RNA_property_flag(prop);
@@ -6688,9 +6501,6 @@ bool RNA_property_is_unlink(PropertyRNA *prop)
   return (flag & (PROP_NEVER_UNLINK | PROP_NEVER_NULL)) == 0;
 }
 
-/* string representation of a property, python
- * compatible but can be used for display too,
- * context may be NULL */
 char *RNA_pointer_as_string_id(bContext *C, PointerRNA *ptr)
 {
   DynStr *dynstr = BLI_dynstr_new();
@@ -6752,7 +6562,6 @@ char *RNA_pointer_as_string(bContext *C,
   return rna_pointer_as_string__bldata(CTX_data_main(C), ptr_prop);
 }
 
-/* context can be NULL */
 char *RNA_pointer_as_string_keywords_ex(bContext *C,
                                         PointerRNA *ptr,
                                         const bool as_function,
@@ -8115,7 +7924,6 @@ bool RNA_property_assign_default(PointerRNA *ptr, PropertyRNA *prop)
   }
 }
 
-/* use RNA_warning macro which includes __func__ suffix */
 void _RNA_warning(const char *format, ...)
 {
   va_list args;
diff --git a/source/blender/makesrna/intern/rna_access_compare_override.c b/source/blender/makesrna/intern/rna_access_compare_override.c
index 6ac44ae6121..8cc6a095c1d 100644
--- a/source/blender/makesrna/intern/rna_access_compare_override.c
+++ b/source/blender/makesrna/intern/rna_access_compare_override.c
@@ -126,8 +126,6 @@ int RNA_property_override_flag(PropertyRNA *prop)
   return rna_ensure_property(prop)->flag_override;
 }
 
-/** \note Does not take into account editable status, this has to be checked separately
- * (using #RNA_property_editable_flag() usually). */
 bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop)
 {
   if (prop->magic == RNA_MAGIC) {
@@ -170,7 +168,6 @@ bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop)
   return (idprop->flag & IDP_FLAG_OVERRIDABLE_LIBRARY) != 0;
 }
 
-/* Should only be used for custom properties */
 bool RNA_property_overridable_library_set(PointerRNA *UNUSED(ptr),
                                           PropertyRNA *prop,
                                           const bool is_overridable)
@@ -635,16 +632,6 @@ static bool rna_property_override_operation_apply(Main *bmain,
   return success;
 }
 
-/**
- * Check whether reference and local overridden data match (are the same),
- * with respect to given restrictive sets of properties.
- * If requested, will generate needed new property overrides, and/or restore values from reference.
- *
- * \param r_report_flags: If given,
- * will be set with flags matching actions taken by the function on \a ptr_local.
- *
- * \return True if _resulting_ \a ptr_local does match \a ptr_reference.
- */
 bool RNA_struct_override_matches(Main *bmain,
                                  PointerRNA *ptr_local,
                                  PointerRNA *ptr_reference,
@@ -928,10 +915,6 @@ bool RNA_struct_override_matches(Main *bmain,
   return matching;
 }
 
-/**
- * Store needed second operands into \a storage data-block
- * for differential override operations.
- */
 bool RNA_struct_override_store(Main *bmain,
                                PointerRNA *ptr_local,
                                PointerRNA *ptr_reference,
@@ -1195,10 +1178,6 @@ static void rna_property_override_apply_ex(Main *bmain,
   }
 }
 
-/**
- * Apply given \a override operations on \a ptr_dst, using \a ptr_src
- * (and \a ptr_storage for differential ops) as source.
- */
 void RNA_struct_override_apply(Main *bmain,
                                PointerRNA *ptr_dst,
                                PointerRNA *ptr_src,
diff --git a/source/blender/makesrna/intern/rna_access_internal.h b/source/blender/makesrna/intern/rna_access_internal.h
index 73407123863..9f1be5bbd67 100644
--- a/source/blender/makesrna/intern/rna_access_internal.h
+++ b/source/blender/makesrna/intern/rna_access_internal.h
@@ -27,6 +27,13 @@
 struct IDProperty;
 struct PropertyRNAOrID;
 
+/**
+ * This function initializes a #PropertyRNAOrID with all required info, from a given #PropertyRNA
+ * and #PointerRNA data. It deals properly with the three cases
+ * (static RNA, runtime RNA, and #IDProperty).
+ * \warning given `ptr` #PointerRNA is assumed to be a valid data one here, calling code is
+ * responsible to ensure that.
+ */
 void rna_property_rna_or_id_get(PropertyRNA *prop,
                                 PointerRNA *ptr,
                                 PropertyRNAOrID *r_prop_rna_or_id);
diff --git a/source/blender/makesrna/intern/rna_armature.c b/source/blender/makesrna/intern/rna_armature.c
index 690506fa517..7a934443907 100644
--- a/source/blender/makesrna/intern/rna_armature.c
+++ b/source/blender/makesrna/intern/rna_armature.c
@@ -669,10 +669,10 @@ static void rna_Armature_transform(bArmature *arm, float mat[16])
 
 #else
 
-/* Settings for curved bbone settings -
- * The posemode values get applied over the top of the editmode ones. */
 void rna_def_bone_curved_common(StructRNA *srna, bool is_posebone, bool is_editbone)
 {
+  /* NOTE: The pose-mode values get applied over the top of the edit-mode ones. */
+
 #  define RNA_DEF_CURVEBONE_UPDATE(prop, is_posebone, is_editbone) \
     { \
       if (is_posebone) { \
diff --git a/source/blender/makesrna/intern/rna_asset.c b/source/blender/makesrna/intern/rna_asset.c
index 0d25a0ba079..e79cbc838d4 100644
--- a/source/blender/makesrna/intern/rna_asset.c
+++ b/source/blender/makesrna/intern/rna_asset.c
@@ -493,9 +493,6 @@ static void rna_def_asset_library_reference(BlenderRNA *brna)
       srna, "Asset Library Reference", "Identifier to refer to the asset library");
 }
 
-/**
- * \note the UI text and updating has to be set by the caller.
- */
 PropertyRNA *rna_def_asset_library_reference_common(struct StructRNA *srna,
                                                     const char *get,
                                                     const char *set)
diff --git a/source/blender/makesrna/intern/rna_constraint.c b/source/blender/makesrna/intern/rna_constraint.c
index bde348c1848..0c993660f39 100644
--- a/source/blender/makesrna/intern/rna_constraint.c
+++ b/source/blender/makesrna/intern/rna_constraint.c
@@ -3446,7 +3446,8 @@ static void rna_def_constraint_transform_cache(BlenderRNA *brna)
   RNA_define_lib_overridable(false);
 }
 
-/* base struct for constraints */
+/* Define the base struct for constraints. */
+
 void RNA_def_constraint(BlenderRNA *brna)
 {
   StructRNA *srna;
diff --git a/source/blender/makesrna/intern/rna_define.c b/source/blender/makesrna/intern/rna_define.c
index bd5ade36eaa..b17ca7d8d59 100644
--- a/source/blender/makesrna/intern/rna_define.c
+++ b/source/blender/makesrna/intern/rna_define.c
@@ -753,10 +753,6 @@ void RNA_define_verify_sdna(bool verify)
   DefRNA.verify = verify;
 }
 
-/**
- * Properties defined when this is enabled are lib-overridable by default (except for Pointer
- * ones).
- */
 void RNA_define_lib_overridable(const bool make_overridable)
 {
   DefRNA.make_overridable = make_overridable;
@@ -915,7 +911,6 @@ static StructDefRNA *rna_find_def_struct(StructRNA *srna)
   return NULL;
 }
 
-/* Struct Definition */
 StructRNA *RNA_def_struct_ptr(BlenderRNA *brna, const char *identifier, StructRNA *srnafrom)
 {
   StructRNA *srna;
@@ -1243,9 +1238,6 @@ void RNA_def_struct_identifier(BlenderRNA *brna, StructRNA *srna, const char *id
   srna->identifier = identifier;
 }
 
-/**
- * Only used in one case when we name the struct for the purpose of useful error messages.
- */
 void RNA_def_struct_identifier_no_struct_map(StructRNA *srna, const char *identifier)
 {
   if (DefRNA.preprocess) {
@@ -1532,13 +1524,6 @@ void RNA_def_property_override_clear_flag(PropertyRNA *prop, PropertyOverrideFla
   prop->flag_override &= ~flag;
 }
 
-/**
- * Add the property-tags passed as \a tags to \a prop (if valid).
- *
- * \note Multiple tags can be set by passing them within \a tags (using bitflags).
- * \note Doesn't do any type-checking with the tags defined in the parent StructRNA
- *       of \a prop. This should be done before (e.g. see #WM_operatortype_prop_tag).
- */
 void RNA_def_property_tags(PropertyRNA *prop, int tags)
 {
   prop->tags |= tags;
@@ -1616,12 +1601,10 @@ void RNA_def_property_array(PropertyRNA *prop, int length)
   }
 }
 
-/* common args for defaults. */
 const float rna_default_quaternion[4] = {1, 0, 0, 0};
 const float rna_default_axis_angle[4] = {0, 0, 1, 0};
 const float rna_default_scale_3d[3] = {1, 1, 1};
 
-/* common args for length */
 const int rna_matrix_dimsize_3x3[] = {3, 3};
 const int rna_matrix_dimsize_4x4[] = {4, 4};
 const int rna_matrix_dimsize_4x2[] = {4, 2};
@@ -1692,17 +1675,6 @@ void RNA_def_property_ui_icon(PropertyRNA *prop, int icon, int consecutive)
   }
 }
 
-/**
- * The values hare are a little confusing:
- *
- * \param step: Used as the value to increase/decrease when clicking on number buttons,
- * as well as scaling mouse input for click-dragging number buttons.
- * For floats this is (step * UI_PRECISION_FLOAT_SCALE), why? - nobody knows.
- * For ints, whole values are used.
- *
- * \param precision: The number of zeros to show
- * (as a whole number - common range is 1 - 6), see UI_PRECISION_FLOAT_MAX
- */
 void RNA_def_property_ui_range(
     PropertyRNA *prop, double min, double max, double step, int precision)
 {
@@ -2082,7 +2054,6 @@ void RNA_def_property_float_default(PropertyRNA *prop, float value)
       break;
   }
 }
-/* array must remain valid after this function finishes */
 void RNA_def_property_float_array_default(PropertyRNA *prop, const float *array)
 {
   StructRNA *srna = DefRNA.laststruct;
@@ -2920,11 +2891,6 @@ void RNA_def_property_editable_array_func(PropertyRNA *prop, const char *editabl
   }
 }
 
-/**
- * Set custom callbacks for override operations handling.
- *
- * \note \a diff callback will also be used by RNA comparison/equality functions.
- */
 void RNA_def_property_override_funcs(PropertyRNA *prop,
                                      const char *diff,
                                      const char *store,
@@ -3813,7 +3779,6 @@ PropertyRNA *RNA_def_enum(StructOrFunctionRNA *cont_,
   return prop;
 }
 
-/* same as above but sets 'PROP_ENUM_FLAG' before setting the default value */
 PropertyRNA *RNA_def_enum_flag(StructOrFunctionRNA *cont_,
                                const char *identifier,
                                const EnumPropertyItem *items,
@@ -4320,7 +4285,6 @@ FunctionRNA *RNA_def_function_runtime(StructRNA *srna, const char *identifier, C
   return func;
 }
 
-/* C return value only!, multiple RNA returns can be done with RNA_def_function_output */
 void RNA_def_function_return(FunctionRNA *func, PropertyRNA *ret)
 {
   if (ret->flag & PROP_DYNAMIC) {
diff --git a/source/blender/makesrna/intern/rna_internal.h b/source/blender/makesrna/intern/rna_internal.h
index fd6664ff0de..c1989a5b10d 100644
--- a/source/blender/makesrna/intern/rna_internal.h
+++ b/source/blender/makesrna/intern/rna_internal.h
@@ -251,6 +251,9 @@ bool rna_AnimaData_override_apply(struct Main *bmain,
 void rna_def_animviz_common(struct StructRNA *srna);
 void rna_def_motionpath_common(struct StructRNA *srna);
 
+/**
+ * Settings for curved bbone settings.
+ */
 void rna_def_bone_curved_common(struct StructRNA *srna, bool is_posebone, bool is_editbone);
 
 void rna_def_texmat_common(struct StructRNA *srna, const char *texspace_editable);
@@ -268,6 +271,9 @@ void rna_def_texpaint_slots(struct BlenderRNA *brna, struct StructRNA *srna);
 void rna_def_view_layer_common(struct BlenderRNA *brna, struct StructRNA *srna, const bool scene);
 
 int rna_AssetMetaData_editable(struct PointerRNA *ptr, const char **r_info);
+/**
+ * \note the UI text and updating has to be set by the caller.
+ */
 PropertyRNA *rna_def_asset_library_reference_common(struct StructRNA *srna,
                                                     const char *get,
                                                     const char *set);
@@ -276,6 +282,9 @@ const EnumPropertyItem *rna_asset_library_reference_itemf(struct bContext *C,
                                                           struct PropertyRNA *prop,
                                                           bool *r_free);
 
+/**
+ * Common properties for Action/Bone Groups - related to color.
+ */
 void rna_def_actionbone_group_common(struct StructRNA *srna,
                                      int update_flag,
                                      const char *update_cb);
@@ -509,8 +518,16 @@ extern StructRNA RNA_PropertyGroupItem;
 extern StructRNA RNA_PropertyGroup;
 #endif
 
+/**
+ * This function only returns an #IDProperty,
+ * or NULL (in case IDProp could not be found, or prop is a real RNA property).
+ */
 struct IDProperty *rna_idproperty_check(struct PropertyRNA **prop,
                                         struct PointerRNA *ptr) ATTR_WARN_UNUSED_RESULT;
+/**
+ * This function always return the valid, real data pointer, be it a regular RNA property one,
+ * or an #IDProperty one.
+ */
 struct PropertyRNA *rna_ensure_property_realdata(struct PropertyRNA **prop,
                                                  struct PointerRNA *ptr) ATTR_WARN_UNUSED_RESULT;
 struct PropertyRNA *rna_ensure_property(struct PropertyRNA *prop) ATTR_WARN_UNUSED_RESULT;
diff --git a/source/blender/makesrna/intern/rna_pose.c b/source/blender/makesrna/intern/rna_pose.c
index 87173adc38f..76bfea00a79 100644
--- a/source/blender/makesrna/intern/rna_pose.c
+++ b/source/blender/makesrna/intern/rna_pose.c
@@ -869,7 +869,6 @@ static void rna_PoseChannel_custom_shape_transform_set(PointerRNA *ptr,
 
 #else
 
-/* common properties for Action/Bone Groups - related to color */
 void rna_def_actionbone_group_common(StructRNA *srna, int update_flag, const char *update_cb)
 {
   PropertyRNA *prop;
diff --git a/source/blender/makesrna/intern/rna_wm.c b/source/blender/makesrna/intern/rna_wm.c
index 1cb1397a0ed..8c128292fd7 100644
--- a/source/blender/makesrna/intern/rna_wm.c
+++ b/source/blender/makesrna/intern/rna_wm.c
@@ -142,9 +142,10 @@ static const EnumPropertyItem event_ndof_type_items[] = {
 };
 #endif /* RNA_RUNTIME */
 
-/* not returned: CAPSLOCKKEY, UNKNOWNKEY */
 const EnumPropertyItem rna_enum_event_type_items[] = {
-    /* Note we abuse 'tooltip' message here to store a 'compact' form of some (too) long names. */
+    /* - Note we abuse 'tooltip' message here to store a 'compact' form of some (too) long names.
+     * - Intentionally excluded: #CAPSLOCKKEY, #UNKNOWNKEY.
+     */
     {0, "NONE", 0, "", ""},
     {LEFTMOUSE, "LEFTMOUSE", 0, "Left Mouse", "LMB"},
     {MIDDLEMOUSE, "MIDDLEMOUSE", 0, "Middle Mouse", "MMB"},