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

Ref T92709

17 files changed, 374 insertions, 307 deletions

diff --git a/source/blender/blenloader/BLO_blend_validate.h b/source/blender/blenloader/BLO_blend_validate.h
index cdbf4bdd952..3a192284661 100644
--- a/source/blender/blenloader/BLO_blend_validate.h
+++ b/source/blender/blenloader/BLO_blend_validate.h
@@ -28,5 +28,12 @@
 struct Main;
 struct ReportList;
 
+/**
+ * Check (but do *not* fix) that all linked data-blocks are still valid
+ * (i.e. pointing to the right library).
+ */
 bool BLO_main_validate_libraries(struct Main *bmain, struct ReportList *reports);
+/**
+ * * Check (and fix if needed) that shape key's 'from' pointer is valid.
+ */
 bool BLO_main_validate_shapekeys(struct Main *bmain, struct ReportList *reports);
diff --git a/source/blender/blenloader/BLO_read_write.h b/source/blender/blenloader/BLO_read_write.h
index ca7ea6d8f09..fe8173e335a 100644
--- a/source/blender/blenloader/BLO_read_write.h
+++ b/source/blender/blenloader/BLO_read_write.h
@@ -58,8 +58,8 @@ struct BlendFileReadReport;
 struct Main;
 struct ReportList;
 
-/* Blend Write API
- * ===============
+/* -------------------------------------------------------------------- */
+/** \name Blend Write API
  *
  * Most functions fall into one of two categories. Either they write a DNA struct or a raw memory
  * buffer to the .blend file.
@@ -91,19 +91,25 @@ struct ReportList;
  * The code that reads this data might have to correct its byte-order. For the common cases
  * there are convenience functions that write and read arrays of simple types such as `int32`.
  * Those will correct endianness automatically.
- */
+ * \{ */
 
-/* Mapping between names and ids. */
+/**
+ * Mapping between names and ids.
+ */
 int BLO_get_struct_id_by_name(BlendWriter *writer, const char *struct_name);
 #define BLO_get_struct_id(writer, struct_name) SDNA_TYPE_FROM_STRUCT(struct_name)
 
-/* Write single struct. */
+/**
+ * Write single struct.
+ */
 void BLO_write_struct_by_name(BlendWriter *writer, const char *struct_name, const void *data_ptr);
 void BLO_write_struct_by_id(BlendWriter *writer, int struct_id, const void *data_ptr);
 #define BLO_write_struct(writer, struct_name, data_ptr) \
   BLO_write_struct_by_id(writer, BLO_get_struct_id(writer, struct_name), data_ptr)
 
-/* Write single struct at address. */
+/**
+ * Write single struct at address.
+ */
 void BLO_write_struct_at_address_by_id(BlendWriter *writer,
                                        int struct_id,
                                        const void *address,
@@ -112,7 +118,9 @@ void BLO_write_struct_at_address_by_id(BlendWriter *writer,
   BLO_write_struct_at_address_by_id( \
       writer, BLO_get_struct_id(writer, struct_name), address, data_ptr)
 
-/* Write single struct at address and specify a filecode. */
+/**
+ * Write single struct at address and specify a file-code.
+ */
 void BLO_write_struct_at_address_by_id_with_filecode(
     BlendWriter *writer, int filecode, int struct_id, const void *address, const void *data_ptr);
 #define BLO_write_struct_at_address_with_filecode( \
@@ -120,7 +128,9 @@ void BLO_write_struct_at_address_by_id_with_filecode(
   BLO_write_struct_at_address_by_id_with_filecode( \
       writer, filecode, BLO_get_struct_id(writer, struct_name), address, data_ptr)
 
-/* Write struct array. */
+/**
+ * Write struct array.
+ */
 void BLO_write_struct_array_by_name(BlendWriter *writer,
                                     const char *struct_name,
                                     int array_size,
@@ -133,14 +143,18 @@ void BLO_write_struct_array_by_id(BlendWriter *writer,
   BLO_write_struct_array_by_id( \
       writer, BLO_get_struct_id(writer, struct_name), array_size, data_ptr)
 
-/* Write struct array at address. */
+/**
+ * Write struct array at address.
+ */
 void BLO_write_struct_array_at_address_by_id(
     BlendWriter *writer, int struct_id, int array_size, const void *address, const void *data_ptr);
 #define BLO_write_struct_array_at_address(writer, struct_name, array_size, address, data_ptr) \
   BLO_write_struct_array_at_address_by_id( \
       writer, BLO_get_struct_id(writer, struct_name), array_size, address, data_ptr)
 
-/* Write struct list. */
+/**
+ * Write struct list.
+ */
 void BLO_write_struct_list_by_name(BlendWriter *writer,
                                    const char *struct_name,
                                    struct ListBase *list);
@@ -148,7 +162,9 @@ void BLO_write_struct_list_by_id(BlendWriter *writer, int struct_id, struct List
 #define BLO_write_struct_list(writer, struct_name, list_ptr) \
   BLO_write_struct_list_by_id(writer, BLO_get_struct_id(writer, struct_name), list_ptr)
 
-/* Write id struct. */
+/**
+ * Write id struct.
+ */
 void blo_write_id_struct(BlendWriter *writer,
                          int struct_id,
                          const void *id_address,
@@ -156,7 +172,9 @@ void blo_write_id_struct(BlendWriter *writer,
 #define BLO_write_id_struct(writer, struct_name, id_address, id) \
   blo_write_id_struct(writer, BLO_get_struct_id(writer, struct_name), id_address, id)
 
-/* Write raw data. */
+/**
+ * Write raw data.
+ */
 void BLO_write_raw(BlendWriter *writer, size_t size_in_bytes, const void *data_ptr);
 void BLO_write_int32_array(BlendWriter *writer, uint num, const int32_t *data_ptr);
 void BLO_write_uint32_array(BlendWriter *writer, uint num, const uint32_t *data_ptr);
@@ -164,13 +182,23 @@ void BLO_write_float_array(BlendWriter *writer, uint num, const float *data_ptr)
 void BLO_write_double_array(BlendWriter *writer, uint num, const double *data_ptr);
 void BLO_write_float3_array(BlendWriter *writer, uint num, const float *data_ptr);
 void BLO_write_pointer_array(BlendWriter *writer, uint num, const void *data_ptr);
+/**
+ * Write a null terminated string.
+ */
 void BLO_write_string(BlendWriter *writer, const char *data_ptr);
 
 /* Misc. */
+
+/**
+ * Sometimes different data is written depending on whether the file is saved to disk or used for
+ * undo. This function returns true when the current file-writing is done for undo.
+ */
 bool BLO_write_is_undo(BlendWriter *writer);
 
-/* Blend Read Data API
- * ===================
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Blend Read Data API
  *
  * Generally, for every BLO_write_* call there should be a corresponding BLO_read_* call.
  *
@@ -181,15 +209,18 @@ bool BLO_write_is_undo(BlendWriter *writer);
  * updated to be NULL. When it was pointing to NULL before, it will stay that way.
  *
  * Examples of matching calls:
- *   BLO_write_struct(writer, ClothSimSettings, clmd->sim_parms);
- *   BLO_read_data_address(reader, &clmd->sim_parms);
  *
- *   BLO_write_struct_list(writer, TimeMarker, &action->markers);
- *   BLO_read_list(reader, &action->markers);
+ * \code{.c}
+ * BLO_write_struct(writer, ClothSimSettings, clmd->sim_parms);
+ * BLO_read_data_address(reader, &clmd->sim_parms);
  *
- *   BLO_write_int32_array(writer, hmd->totindex, hmd->indexar);
- *   BLO_read_int32_array(reader, hmd->totindex, &hmd->indexar);
- */
+ * BLO_write_struct_list(writer, TimeMarker, &action->markers);
+ * BLO_read_list(reader, &action->markers);
+ *
+ * BLO_write_int32_array(writer, hmd->totindex, hmd->indexar);
+ * BLO_read_int32_array(reader, hmd->totindex, &hmd->indexar);
+ * \endcode
+ * \{ */
 
 void *BLO_read_get_new_data_address(BlendDataReader *reader, const void *old_address);
 void *BLO_read_get_new_data_address_no_us(BlendDataReader *reader, const void *old_address);
@@ -201,10 +232,16 @@ void *BLO_read_get_new_packed_address(BlendDataReader *reader, const void *old_a
   *((void **)ptr_p) = BLO_read_get_new_packed_address((reader), *(ptr_p))
 
 typedef void (*BlendReadListFn)(BlendDataReader *reader, void *data);
+/**
+ * Updates all ->prev and ->next pointers of the list elements.
+ * Updates the list->first and list->last pointers.
+ * When not NULL, calls the callback on every element.
+ */
 void BLO_read_list_cb(BlendDataReader *reader, struct ListBase *list, BlendReadListFn callback);
 void BLO_read_list(BlendDataReader *reader, struct ListBase *list);
 
 /* Update data pointers and correct byte-order if necessary. */
+
 void BLO_read_int32_array(BlendDataReader *reader, int array_size, int32_t **ptr_p);
 void BLO_read_uint32_array(BlendDataReader *reader, int array_size, uint32_t **ptr_p);
 void BLO_read_float_array(BlendDataReader *reader, int array_size, float **ptr_p);
@@ -213,18 +250,21 @@ void BLO_read_double_array(BlendDataReader *reader, int array_size, double **ptr
 void BLO_read_pointer_array(BlendDataReader *reader, void **ptr_p);
 
 /* Misc. */
+
 bool BLO_read_requires_endian_switch(BlendDataReader *reader);
 bool BLO_read_data_is_undo(BlendDataReader *reader);
 void BLO_read_data_globmap_add(BlendDataReader *reader, void *oldaddr, void *newaddr);
 void BLO_read_glob_list(BlendDataReader *reader, struct ListBase *list);
 struct BlendFileReadReport *BLO_read_data_reports(BlendDataReader *reader);
 
-/* Blend Read Lib API
- * ===================
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Blend Read Lib API
  *
- * This API does almost the same as the Blend Read Data API. However, now only pointers to ID data
- * blocks are updated.
- */
+ * This API does almost the same as the Blend Read Data API.
+ * However, now only pointers to ID data blocks are updated.
+ * \{ */
 
 ID *BLO_read_get_new_id_address(BlendLibReader *reader, struct Library *lib, struct ID *id);
 
@@ -232,30 +272,44 @@ ID *BLO_read_get_new_id_address(BlendLibReader *reader, struct Library *lib, str
   *((void **)id_ptr_p) = (void *)BLO_read_get_new_id_address((reader), (lib), (ID *)*(id_ptr_p))
 
 /* Misc. */
+
 bool BLO_read_lib_is_undo(BlendLibReader *reader);
 struct Main *BLO_read_lib_get_main(BlendLibReader *reader);
 struct BlendFileReadReport *BLO_read_lib_reports(BlendLibReader *reader);
 
-/* Blend Expand API
- * ===================
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Blend Expand API
  *
  * BLO_expand has to be called for every data block that should be loaded. If the data block is in
- * a separate .blend file, it will be pulled from there.
- */
+ * a separate `.blend` file, it will be pulled from there.
+ * \{ */
 
 void BLO_expand_id(BlendExpander *expander, struct ID *id);
 
 #define BLO_expand(expander, id) BLO_expand_id(expander, (struct ID *)id)
 
-/* Report API
- * ===================
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Report API
+ * \{ */
 
+/**
+ * This function ensures that reports are printed,
+ * in the case of library linking errors this is important!
+ *
+ * bit kludge but better than doubling up on prints,
+ * we could alternatively have a versions of a report function which forces printing - campbell
+ */
 void BLO_reportf_wrap(struct BlendFileReadReport *reports,
                       eReportType type,
                       const char *format,
                       ...) ATTR_PRINTF_FORMAT(3, 4);
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/source/blender/blenloader/BLO_readfile.h b/source/blender/blenloader/BLO_readfile.h
index 70006bb6d23..f86528db452 100644
--- a/source/blender/blenloader/BLO_readfile.h
+++ b/source/blender/blenloader/BLO_readfile.h
@@ -144,19 +144,50 @@ typedef enum eBLOReadSkip {
 } eBLOReadSkip;
 #define BLO_READ_SKIP_ALL (BLO_READ_SKIP_USERDEF | BLO_READ_SKIP_DATA)
 
+/**
+ * Open a blender file from a pathname. The function returns NULL
+ * and sets a report in the list if it cannot open the file.
+ *
+ * \param filepath: The path of the file to open.
+ * \param reports: If the return value is NULL, errors indicating the cause of the failure.
+ * \return The data of the file.
+ */
 BlendFileData *BLO_read_from_file(const char *filepath,
                                   eBLOReadSkip skip_flags,
                                   struct BlendFileReadReport *reports);
+/**
+ * Open a blender file from memory. The function returns NULL
+ * and sets a report in the list if it cannot open the file.
+ *
+ * \param mem: The file data.
+ * \param memsize: The length of \a mem.
+ * \param reports: If the return value is NULL, errors indicating the cause of the failure.
+ * \return The data of the file.
+ */
 BlendFileData *BLO_read_from_memory(const void *mem,
                                     int memsize,
                                     eBLOReadSkip skip_flags,
                                     struct ReportList *reports);
+/**
+ * Used for undo/redo, skips part of libraries reading
+ * (assuming their data are already loaded & valid).
+ *
+ * \param oldmain: old main,
+ * from which we will keep libraries and other data-blocks that should not have changed.
+ * \param filename: current file, only for retrieving library data.
+ */
 BlendFileData *BLO_read_from_memfile(struct Main *oldmain,
                                      const char *filename,
                                      struct MemFile *memfile,
                                      const struct BlendFileReadParams *params,
                                      struct ReportList *reports);
 
+/**
+ * Frees a BlendFileData structure and *all* the data associated with it
+ * (the userdef data, and the main libblock data).
+ *
+ * \param bfd: The structure to free.
+ */
 void BLO_blendfiledata_free(BlendFileData *bfd);
 
 /** \} */
@@ -170,24 +201,89 @@ typedef struct BLODataBlockInfo {
   struct AssetMetaData *asset_data;
 } BLODataBlockInfo;
 
+/**
+ * Open a blendhandle from a file path.
+ *
+ * \param filepath: The file path to open.
+ * \param reports: Report errors in opening the file (can be NULL).
+ * \return A handle on success, or NULL on failure.
+ */
 BlendHandle *BLO_blendhandle_from_file(const char *filepath, struct BlendFileReadReport *reports);
+/**
+ * Open a blendhandle from memory.
+ *
+ * \param mem: The data to load from.
+ * \param memsize: The size of the data.
+ * \return A handle on success, or NULL on failure.
+ */
 BlendHandle *BLO_blendhandle_from_memory(const void *mem,
                                          int memsize,
                                          struct BlendFileReadReport *reports);
 
+/**
+ * Gets the names of all the data-blocks in a file of a certain type
+ * (e.g. all the scene names in a file).
+ *
+ * \param bh: The blendhandle to access.
+ * \param ofblocktype: The type of names to get.
+ * \param tot_names: The length of the returned list.
+ * \param use_assets_only: Only list IDs marked as assets.
+ * \return A BLI_linklist of strings. The string links should be freed with #MEM_freeN().
+ */
 struct LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh,
                                                      int ofblocktype,
 
                                                      const bool use_assets_only,
                                                      int *r_tot_names);
+/**
+ * Gets the names and asset-data (if ID is an asset) of data-blocks in a file of a certain type.
+ * The data-blocks can be limited to assets.
+ *
+ * \param bh: The blendhandle to access.
+ * \param ofblocktype: The type of names to get.
+ * \param use_assets_only: Limit the result to assets only.
+ * \param tot_info_items: The length of the returned list.
+ * \return A BLI_linklist of `BLODataBlockInfo *`.
+ * The links and #BLODataBlockInfo.asset_data should be freed with MEM_freeN.
+ */
 struct LinkNode * /*BLODataBlockInfo */ BLO_blendhandle_get_datablock_info(
     BlendHandle *bh, int ofblocktype, const bool use_assets_only, int *r_tot_info_items);
+/**
+ * Gets the previews of all the data-blocks in a file of a certain type
+ * (e.g. all the scene previews in a file).
+ *
+ * \param bh: The blendhandle to access.
+ * \param ofblocktype: The type of names to get.
+ * \param r_tot_prev: The length of the returned list.
+ * \return A BLI_linklist of #PreviewImage. The #PreviewImage links should be freed with malloc.
+ */
 struct LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *r_tot_prev);
+/**
+ * Get the PreviewImage of a single data block in a file.
+ * (e.g. all the scene previews in a file).
+ *
+ * \param bh: The blendhandle to access.
+ * \param ofblocktype: The type of names to get.
+ * \param name: Name of the block without the ID_ prefix, to read the preview image from.
+ * \return PreviewImage or NULL when no preview Images have been found. Caller owns the returned
+ */
 struct PreviewImage *BLO_blendhandle_get_preview_for_id(BlendHandle *bh,
                                                         int ofblocktype,
                                                         const char *name);
+/**
+ * Gets the names of all the linkable data-block types available in a file.
+ * (e.g. "Scene", "Mesh", "Light", etc.).
+ *
+ * \param bh: The blendhandle to access.
+ * \return A BLI_linklist of strings. The string links should be freed with #MEM_freeN().
+ */
 struct LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh);
 
+/**
+ * Close and free a blendhandle. The handle becomes invalid after this call.
+ *
+ * \param bh: The handle to close.
+ */
 void BLO_blendhandle_close(BlendHandle *bh);
 
 /** \} */
@@ -195,7 +291,25 @@ void BLO_blendhandle_close(BlendHandle *bh);
 #define BLO_GROUP_MAX 32
 #define BLO_EMBEDDED_STARTUP_BLEND "<startup.blend>"
 
+/**
+ * Check whether given path ends with a blend file compatible extension
+ * (`.blend`, `.ble` or `.blend.gz`).
+ *
+ * \param str: The path to check.
+ * \return true is this path ends with a blender file extension.
+ */
 bool BLO_has_bfile_extension(const char *str);
+/**
+ * Try to explode given path into its 'library components'
+ * (i.e. a .blend file, id type/group, and data-block itself).
+ *
+ * \param path: the full path to explode.
+ * \param r_dir: the string that'll contain path up to blend file itself ('library' path).
+ * WARNING! Must be #FILE_MAX_LIBEXTRA long (it also stores group and name strings)!
+ * \param r_group: the string that'll contain 'group' part of the path, if any. May be NULL.
+ * \param r_name: the string that'll contain data's name part of the path, if any. May be NULL.
+ * \return true if path contains a blend file.
+ */
 bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, char **r_name);
 
 /* -------------------------------------------------------------------- */
@@ -263,14 +377,41 @@ void BLO_library_link_params_init_with_context(struct LibraryLink_Params *params
                                                struct ViewLayer *view_layer,
                                                const struct View3D *v3d);
 
+/**
+ * Initialize the #BlendHandle for linking library data.
+ *
+ * \param bh: A blender file handle as returned by
+ * #BLO_blendhandle_from_file or #BLO_blendhandle_from_memory.
+ * \param filepath: Used for relative linking, copied to the `lib->filepath`.
+ * \param params: Settings for linking that don't change from beginning to end of linking.
+ * \return the library #Main, to be passed to #BLO_library_link_named_part as \a mainl.
+ */
 struct Main *BLO_library_link_begin(BlendHandle **bh,
                                     const char *filepath,
                                     const struct LibraryLink_Params *params);
+/**
+ * Link a named data-block from an external blend file.
+ *
+ * \param mainl: The main database to link from (not the active one).
+ * \param bh: The blender file handle.
+ * \param idcode: The kind of data-block to link.
+ * \param name: The name of the data-block (without the 2 char ID prefix).
+ * \return the linked ID when found.
+ */
 struct ID *BLO_library_link_named_part(struct Main *mainl,
                                        BlendHandle **bh,
                                        const short idcode,
                                        const char *name,
                                        const struct LibraryLink_Params *params);
+/**
+ * Finalize linking from a given .blend file (library).
+ * Optionally instance the indirect object/collection in the scene when the flags are set.
+ * \note Do not use \a bh after calling this function, it may frees it.
+ *
+ * \param mainl: The main database to link from (not the active one).
+ * \param bh: The blender file handle (WARNING! may be freed by this function!).
+ * \param params: Settings for linking that don't change from beginning to end of linking.
+ */
 void BLO_library_link_end(struct Main *mainl,
                           BlendHandle **bh,
                           const struct LibraryLink_Params *params);
@@ -304,6 +445,10 @@ void BLO_library_temp_free(TempLibraryContext *temp_lib_ctx);
 void *BLO_library_read_struct(struct FileData *fd, struct BHead *bh, const char *blockname);
 
 /* internal function but we need to expose it */
+/**
+ * Used to link a file (without UI) to the current UI.
+ * Note that it assumes the old pointers in UI are still valid, so old Main is not freed.
+ */
 void blo_lib_link_restore(struct Main *oldmain,
                           struct Main *newmain,
                           struct wmWindowManager *curwm,
@@ -312,19 +457,48 @@ void blo_lib_link_restore(struct Main *oldmain,
 
 typedef void (*BLOExpandDoitCallback)(void *fdhandle, struct Main *mainvar, void *idv);
 
+/**
+ * Set the callback func used over all ID data found by \a BLO_expand_main func.
+ *
+ * \param expand_doit_func: Called for each ID block it finds.
+ */
 void BLO_main_expander(BLOExpandDoitCallback expand_doit_func);
+/**
+ * Loop over all ID data in Main to mark relations.
+ * Set (id->tag & LIB_TAG_NEED_EXPAND) to mark expanding. Flags get cleared after expanding.
+ *
+ * \param fdhandle: usually filedata, or own handle.
+ * \param mainvar: the Main database to expand.
+ */
 void BLO_expand_main(void *fdhandle, struct Main *mainvar);
 
 /**
  * Update defaults in startup.blend, without having to save and embed it.
  * \note defaults for preferences are stored in `userdef_default.c` and can be updated there.
  */
+/**
+ * Update defaults in startup.blend, without having to save and embed the file.
+ * This function can be emptied each time the startup.blend is updated.
+ *
+ * \note Screen data may be cleared at this point, this will happen in the case
+ * an app-template's data needs to be versioned when read-file is called with "Load UI" disabled.
+ * Versioning the screen data can be safely skipped without "Load UI" since the screen data
+ * will have been versioned when it was first loaded.
+ */
 void BLO_update_defaults_startup_blend(struct Main *bmain, const char *app_template);
 void BLO_update_defaults_workspace(struct WorkSpace *workspace, const char *app_template);
 
 /* Disable unwanted experimental feature settings on startup. */
 void BLO_sanitize_experimental_features_userpref_blend(struct UserDef *userdef);
 
+/**
+ * Does a very light reading of given .blend file to extract its stored thumbnail.
+ *
+ * \param filepath: The path of the file to extract thumbnail from.
+ * \return The raw thumbnail
+ * (MEM-allocated, as stored in file, use #BKE_main_thumbnail_to_imbuf()
+ * to convert it to ImBuf image).
+ */
 struct BlendThumbnail *BLO_thumbnail_from_file(const char *filepath);
 
 /* datafiles (generated theme) */
diff --git a/source/blender/blenloader/BLO_undofile.h b/source/blender/blenloader/BLO_undofile.h
index b2cf1cd27b5..0e2c22d7e4d 100644
--- a/source/blender/blenloader/BLO_undofile.h
+++ b/source/blender/blenloader/BLO_undofile.h
@@ -87,14 +87,31 @@ void BLO_memfile_write_finalize(MemFileWriteData *mem_data);
 void BLO_memfile_chunk_add(MemFileWriteData *mem_data, const char *buf, size_t size);
 
 /* exports */
+
+/**
+ * Not memfile itself.
+ */
 extern void BLO_memfile_free(MemFile *memfile);
+/**
+ * Result is that 'first' is being freed.
+ * to keep list of memfiles consistent, 'first' is always first in list.
+ */
 extern void BLO_memfile_merge(MemFile *first, MemFile *second);
+/**
+ * Clear is_identical_future before adding next memfile.
+ */
 extern void BLO_memfile_clear_future(MemFile *memfile);
 
-/* utilities */
+/* Utilities. */
+
 extern struct Main *BLO_memfile_main_get(struct MemFile *memfile,
                                          struct Main *bmain,
                                          struct Scene **r_scene);
+/**
+ * Saves .blend using undo buffer.
+ *
+ * \return success.
+ */
 extern bool BLO_memfile_write_file(struct MemFile *memfile, const char *filename);
 
 FileReader *BLO_memfile_new_filereader(MemFile *memfile, int undo_direction);
diff --git a/source/blender/blenloader/BLO_writefile.h b/source/blender/blenloader/BLO_writefile.h
index 57f5b5de1f0..9bc3714ff38 100644
--- a/source/blender/blenloader/BLO_writefile.h
+++ b/source/blender/blenloader/BLO_writefile.h
@@ -64,12 +64,18 @@ struct BlendFileWriteParams {
   const struct BlendThumbnail *thumb;
 };
 
+/**
+ * \return Success.
+ */
 extern bool BLO_write_file(struct Main *mainvar,
                            const char *filepath,
                            const int write_flags,
                            const struct BlendFileWriteParams *params,
                            struct ReportList *reports);
 
+/**
+ * \return Success.
+ */
 extern bool BLO_write_file_mem(struct Main *mainvar,
                                struct MemFile *compare,
                                struct MemFile *current,
diff --git a/source/blender/blenloader/intern/blend_validate.c b/source/blender/blenloader/intern/blend_validate.c
index 7d641d976e3..333f6e341c6 100644
--- a/source/blender/blenloader/intern/blend_validate.c
+++ b/source/blender/blenloader/intern/blend_validate.c
@@ -47,10 +47,6 @@
 
 #include "readfile.h"
 
-/**
- * Check (but do *not* fix) that all linked data-blocks are still valid
- * (i.e. pointing to the right library).
- */
 bool BLO_main_validate_libraries(Main *bmain, ReportList *reports)
 {
   ListBase mainlist;
@@ -165,7 +161,6 @@ bool BLO_main_validate_libraries(Main *bmain, ReportList *reports)
   return is_valid;
 }
 
-/** Check (and fix if needed) that shape key's 'from' pointer is valid. */
 bool BLO_main_validate_shapekeys(Main *bmain, ReportList *reports)
 {
   ListBase *lb;
diff --git a/source/blender/blenloader/intern/readblenentry.c b/source/blender/blenloader/intern/readblenentry.c
index c0fdfa86907..f3c92aec338 100644
--- a/source/blender/blenloader/intern/readblenentry.c
+++ b/source/blender/blenloader/intern/readblenentry.c
@@ -61,13 +61,6 @@ void BLO_blendhandle_print_sizes(BlendHandle *bh, void *fp);
 
 /* Access routines used by filesel. */
 
-/**
- * Open a blendhandle from a file path.
- *
- * \param filepath: The file path to open.
- * \param reports: Report errors in opening the file (can be NULL).
- * \return A handle on success, or NULL on failure.
- */
 BlendHandle *BLO_blendhandle_from_file(const char *filepath, BlendFileReadReport *reports)
 {
   BlendHandle *bh;
@@ -77,13 +70,6 @@ BlendHandle *BLO_blendhandle_from_file(const char *filepath, BlendFileReadReport
   return bh;
 }
 
-/**
- * Open a blendhandle from memory.
- *
- * \param mem: The data to load from.
- * \param memsize: The size of the data.
- * \return A handle on success, or NULL on failure.
- */
 BlendHandle *BLO_blendhandle_from_memory(const void *mem,
                                          int memsize,
                                          BlendFileReadReport *reports)
@@ -130,16 +116,6 @@ void BLO_blendhandle_print_sizes(BlendHandle *bh, void *fp)
   fprintf(fp, "]\n");
 }
 
-/**
- * Gets the names of all the data-blocks in a file of a certain type
- * (e.g. all the scene names in a file).
- *
- * \param bh: The blendhandle to access.
- * \param ofblocktype: The type of names to get.
- * \param tot_names: The length of the returned list.
- * \param use_assets_only: Only list IDs marked as assets.
- * \return A BLI_linklist of strings. The string links should be freed with #MEM_freeN().
- */
 LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh,
                                               int ofblocktype,
                                               const bool use_assets_only,
@@ -169,17 +145,6 @@ LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh,
   return names;
 }
 
-/**
- * Gets the names and asset-data (if ID is an asset) of data-blocks in a file of a certain type.
- * The data-blocks can be limited to assets.
- *
- * \param bh: The blendhandle to access.
- * \param ofblocktype: The type of names to get.
- * \param use_assets_only: Limit the result to assets only.
- * \param tot_info_items: The length of the returned list.
- * \return A BLI_linklist of BLODataBlockInfo *. The links and #BLODataBlockInfo.asset_data should
- *         be freed with MEM_freeN.
- */
 LinkNode *BLO_blendhandle_get_datablock_info(BlendHandle *bh,
                                              int ofblocktype,
                                              const bool use_assets_only,
@@ -267,15 +232,6 @@ static BHead *blo_blendhandle_read_preview_rects(FileData *fd,
   return bhead;
 }
 
-/**
- * Get the PreviewImage of a single data block in a file.
- * (e.g. all the scene previews in a file).
- *
- * \param bh: The blendhandle to access.
- * \param ofblocktype: The type of names to get.
- * \param name: Name of the block without the ID_ prefix, to read the preview image from.
- * \return PreviewImage or NULL when no preview Images have been found. Caller owns the returned
- */
 PreviewImage *BLO_blendhandle_get_preview_for_id(BlendHandle *bh,
                                                  int ofblocktype,
                                                  const char *name)
@@ -315,15 +271,6 @@ PreviewImage *BLO_blendhandle_get_preview_for_id(BlendHandle *bh,
   return NULL;
 }
 
-/**
- * Gets the previews of all the data-blocks in a file of a certain type
- * (e.g. all the scene previews in a file).
- *
- * \param bh: The blendhandle to access.
- * \param ofblocktype: The type of names to get.
- * \param r_tot_prev: The length of the returned list.
- * \return A BLI_linklist of PreviewImage. The PreviewImage links should be freed with malloc.
- */
 LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *r_tot_prev)
 {
   FileData *fd = (FileData *)bh;
@@ -384,13 +331,6 @@ LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *r_
   return previews;
 }
 
-/**
- * Gets the names of all the linkable data-block types available in a file.
- * (e.g. "Scene", "Mesh", "Light", etc.).
- *
- * \param bh: The blendhandle to access.
- * \return A BLI_linklist of strings. The string links should be freed with #MEM_freeN().
- */
 LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh)
 {
   FileData *fd = (FileData *)bh;
@@ -418,11 +358,6 @@ LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh)
   return names;
 }
 
-/**
- * Close and free a blendhandle. The handle becomes invalid after this call.
- *
- * \param bh: The handle to close.
- */
 void BLO_blendhandle_close(BlendHandle *bh)
 {
   FileData *fd = (FileData *)bh;
@@ -432,14 +367,6 @@ void BLO_blendhandle_close(BlendHandle *bh)
 
 /**********/
 
-/**
- * Open a blender file from a pathname. The function returns NULL
- * and sets a report in the list if it cannot open the file.
- *
- * \param filepath: The path of the file to open.
- * \param reports: If the return value is NULL, errors indicating the cause of the failure.
- * \return The data of the file.
- */
 BlendFileData *BLO_read_from_file(const char *filepath,
                                   eBLOReadSkip skip_flags,
                                   BlendFileReadReport *reports)
@@ -457,15 +384,6 @@ BlendFileData *BLO_read_from_file(const char *filepath,
   return bfd;
 }
 
-/**
- * Open a blender file from memory. The function returns NULL
- * and sets a report in the list if it cannot open the file.
- *
- * \param mem: The file data.
- * \param memsize: The length of \a mem.
- * \param reports: If the return value is NULL, errors indicating the cause of the failure.
- * \return The data of the file.
- */
 BlendFileData *BLO_read_from_memory(const void *mem,
                                     int memsize,
                                     eBLOReadSkip skip_flags,
@@ -485,14 +403,6 @@ BlendFileData *BLO_read_from_memory(const void *mem,
   return bfd;
 }
 
-/**
- * Used for undo/redo, skips part of libraries reading
- * (assuming their data are already loaded & valid).
- *
- * \param oldmain: old main,
- * from which we will keep libraries and other data-blocks that should not have changed.
- * \param filename: current file, only for retrieving library data.
- */
 BlendFileData *BLO_read_from_memfile(Main *oldmain,
                                      const char *filename,
                                      MemFile *memfile,
@@ -548,12 +458,6 @@ BlendFileData *BLO_read_from_memfile(Main *oldmain,
   return bfd;
 }
 
-/**
- * Frees a BlendFileData structure and *all* the data associated with it
- * (the userdef data, and the main libblock data).
- *
- * \param bfd: The structure to free.
- */
 void BLO_blendfiledata_free(BlendFileData *bfd)
 {
   if (bfd->main) {
diff --git a/source/blender/blenloader/intern/readfile.c b/source/blender/blenloader/intern/readfile.c
index 3ed32b196eb..3532918c3b6 100644
--- a/source/blender/blenloader/intern/readfile.c
+++ b/source/blender/blenloader/intern/readfile.c
@@ -214,13 +214,6 @@ typedef struct BHeadN {
  * because ID names are used in lookup tables. */
 #define BHEAD_USE_READ_ON_DEMAND(bhead) ((bhead)->code == DATA)
 
-/**
- * This function ensures that reports are printed,
- * in the case of library linking errors this is important!
- *
- * bit kludge but better than doubling up on prints,
- * we could alternatively have a versions of a report function which forces printing - campbell
- */
 void BLO_reportf_wrap(BlendFileReadReport *reports, eReportType type, const char *format, ...)
 {
   char fixed_buf[1024]; /* should be long enough */
@@ -997,13 +990,11 @@ static BHead *blo_bhead_read_full(FileData *fd, BHead *thisblock)
 }
 #endif /* USE_BHEAD_READ_ON_DEMAND */
 
-/* Warning! Caller's responsibility to ensure given bhead **is** an ID one! */
 const char *blo_bhead_id_name(const FileData *fd, const BHead *bhead)
 {
   return (const char *)POINTER_OFFSET(bhead, sizeof(*bhead) + fd->id_name_offset);
 }
 
-/* Warning! Caller's responsibility to ensure given bhead **is** an ID one! */
 AssetMetaData *blo_bhead_id_asset_data_address(const FileData *fd, const BHead *bhead)
 {
   BLI_assert(blo_bhead_is_id_valid_type(bhead));
@@ -1269,8 +1260,6 @@ static FileData *blo_filedata_from_file_open(const char *filepath, BlendFileRead
   return blo_filedata_from_file_descriptor(filepath, reports, file);
 }
 
-/* cannot be called with relative paths anymore! */
-/* on each new library added, it now checks for the current FileData and expands relativeness */
 FileData *blo_filedata_from_file(const char *filepath, BlendFileReadReport *reports)
 {
   FileData *fd = blo_filedata_from_file_open(filepath, reports);
@@ -1411,30 +1400,12 @@ void blo_filedata_free(FileData *fd)
 /** \name Public Utilities
  * \{ */
 
-/**
- * Check whether given path ends with a blend file compatible extension
- * (`.blend`, `.ble` or `.blend.gz`).
- *
- * \param str: The path to check.
- * \return true is this path ends with a blender file extension.
- */
 bool BLO_has_bfile_extension(const char *str)
 {
   const char *ext_test[4] = {".blend", ".ble", ".blend.gz", NULL};
   return BLI_path_extension_check_array(str, ext_test);
 }
 
-/**
- * Try to explode given path into its 'library components'
- * (i.e. a .blend file, id type/group, and data-block itself).
- *
- * \param path: the full path to explode.
- * \param r_dir: the string that'll contain path up to blend file itself ('library' path).
- * WARNING! Must be #FILE_MAX_LIBEXTRA long (it also stores group and name strings)!
- * \param r_group: the string that'll contain 'group' part of the path, if any. May be NULL.
- * \param r_name: the string that'll contain data's name part of the path, if any. May be NULL.
- * \return true if path contains a blend file.
- */
 bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, char **r_name)
 {
   /* We might get some data names with slashes,
@@ -1495,14 +1466,6 @@ bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, cha
   return true;
 }
 
-/**
- * Does a very light reading of given .blend file to extract its stored thumbnail.
- *
- * \param filepath: The path of the file to extract thumbnail from.
- * \return The raw thumbnail
- * (MEM-allocated, as stored in file, use #BKE_main_thumbnail_to_imbuf()
- * to convert it to ImBuf image).
- */
 BlendThumbnail *BLO_thumbnail_from_file(const char *filepath)
 {
   FileData *fd;
@@ -1551,7 +1514,6 @@ static void *newdataadr_no_us(FileData *fd, const void *adr)
   return oldnewmap_lookup_and_inc(fd->datamap, adr, false);
 }
 
-/* Direct datablocks with global linking. */
 void *blo_read_get_new_globaldata_address(FileData *fd, const void *adr)
 {
   return oldnewmap_lookup_and_inc(fd->globmap, adr, true);
@@ -1573,7 +1535,6 @@ static void *newlibadr(FileData *fd, const void *lib, const void *adr)
   return oldnewmap_liblookup(fd->libmap, adr, lib);
 }
 
-/* only lib data */
 void *blo_do_versions_newlibadr(FileData *fd, const void *lib, const void *adr)
 {
   return newlibadr(fd, lib, adr);
@@ -1615,12 +1576,6 @@ static void change_link_placeholder_to_real_ID_pointer(ListBase *mainlist,
   }
 }
 
-/* lib linked proxy objects point to our local data, we need
- * to clear that pointer before reading the undo memfile since
- * the object might be removed, it is set again in reading
- * if the local object still exists.
- * This is only valid for local proxy objects though, linked ones should not be affected here.
- */
 void blo_clear_proxy_pointers_from_lib(Main *oldmain)
 {
   LISTBASE_FOREACH (Object *, ob, &oldmain->objects) {
@@ -1680,8 +1635,6 @@ void blo_make_packed_pointer_map(FileData *fd, Main *oldmain)
   }
 }
 
-/* set old main packed data to zero if it has been restored */
-/* this works because freeing old main only happens after this call */
 void blo_end_packed_pointer_map(FileData *fd, Main *oldmain)
 {
   OldNew *entry = fd->packedmap->entries;
@@ -1718,7 +1671,6 @@ void blo_end_packed_pointer_map(FileData *fd, Main *oldmain)
   }
 }
 
-/* undo file support: add all library pointers in lookup */
 void blo_add_library_pointer_map(ListBase *old_mainlist, FileData *fd)
 {
   ListBase *lbarray[INDEX_ID_MAX];
@@ -1735,8 +1687,6 @@ void blo_add_library_pointer_map(ListBase *old_mainlist, FileData *fd)
   fd->old_mainlist = old_mainlist;
 }
 
-/* Build a GSet of old main (we only care about local data here, so we can do that after
- * split_main() call. */
 void blo_make_old_idmap_from_main(FileData *fd, Main *bmain)
 {
   if (fd->old_idmap != NULL) {
@@ -2770,10 +2720,6 @@ static void lib_link_workspace_layout_restore(struct IDNameLib_Map *id_map,
   }
 }
 
-/**
- * Used to link a file (without UI) to the current UI.
- * Note that it assumes the old pointers in UI are still valid, so old Main is not freed.
- */
 void blo_lib_link_restore(Main *oldmain,
                           Main *newmain,
                           wmWindowManager *curwm,
@@ -4383,23 +4329,11 @@ static void expand_id(BlendExpander *expander, ID *id)
   expand_id_embedded_id(expander, id);
 }
 
-/**
- * Set the callback func used over all ID data found by \a BLO_expand_main func.
- *
- * \param expand_doit_func: Called for each ID block it finds.
- */
 void BLO_main_expander(BLOExpandDoitCallback expand_doit_func)
 {
   expand_doit = expand_doit_func;
 }
 
-/**
- * Loop over all ID data in Main to mark relations.
- * Set (id->tag & LIB_TAG_NEED_EXPAND) to mark expanding. Flags get cleared after expanding.
- *
- * \param fdhandle: usually filedata, or own handle.
- * \param mainvar: the Main database to expand.
- */
 void BLO_expand_main(void *fdhandle, Main *mainvar)
 {
   ListBase *lbarray[INDEX_ID_MAX];
@@ -4492,15 +4426,6 @@ static ID *link_named_part(
   return id;
 }
 
-/**
- * Link a named data-block from an external blend file.
- *
- * \param mainl: The main database to link from (not the active one).
- * \param bh: The blender file handle.
- * \param idcode: The kind of data-block to link.
- * \param name: The name of the data-block (without the 2 char ID prefix).
- * \return the linked ID when found.
- */
 ID *BLO_library_link_named_part(Main *mainl,
                                 BlendHandle **bh,
                                 const short idcode,
@@ -4573,15 +4498,6 @@ void BLO_library_link_params_init_with_context(struct LibraryLink_Params *params
   }
 }
 
-/**
- * Initialize the #BlendHandle for linking library data.
- *
- * \param bh: A blender file handle as returned by
- * #BLO_blendhandle_from_file or #BLO_blendhandle_from_memory.
- * \param filepath: Used for relative linking, copied to the `lib->filepath`.
- * \param params: Settings for linking that don't change from beginning to end of linking.
- * \return the library #Main, to be passed to #BLO_library_link_named_part as \a mainl.
- */
 Main *BLO_library_link_begin(BlendHandle **bh,
                              const char *filepath,
                              const struct LibraryLink_Params *params)
@@ -4706,15 +4622,6 @@ static void library_link_end(Main *mainl, FileData **fd, const int flag)
   }
 }
 
-/**
- * Finalize linking from a given .blend file (library).
- * Optionally instance the indirect object/collection in the scene when the flags are set.
- * \note Do not use \a bh after calling this function, it may frees it.
- *
- * \param mainl: The main database to link from (not the active one).
- * \param bh: The blender file handle (WARNING! may be freed by this function!).
- * \param params: Settings for linking that don't change from beginning to end of linking.
- */
 void BLO_library_link_end(Main *mainl, BlendHandle **bh, const struct LibraryLink_Params *params)
 {
   FileData *fd = (FileData *)(*bh);
@@ -5070,11 +4977,6 @@ bool BLO_read_requires_endian_switch(BlendDataReader *reader)
   return (reader->fd->flags & FD_FLAGS_SWITCH_ENDIAN) != 0;
 }
 
-/**
- * Updates all ->prev and ->next pointers of the list elements.
- * Updates the list->first and list->last pointers.
- * When not NULL, calls the callback on every element.
- */
 void BLO_read_list_cb(BlendDataReader *reader, ListBase *list, BlendReadListFn callback)
 {
   if (BLI_listbase_is_empty(list)) {
diff --git a/source/blender/blenloader/intern/readfile.h b/source/blender/blenloader/intern/readfile.h
index 75152a05063..3b5be3dd013 100644
--- a/source/blender/blenloader/intern/readfile.h
+++ b/source/blender/blenloader/intern/readfile.h
@@ -131,6 +131,11 @@ void blo_split_main(ListBase *mainlist, struct Main *main);
 
 BlendFileData *blo_read_file_internal(FileData *fd, const char *filepath);
 
+/**
+ * On each new library added, it now checks for the current #FileData and expands relativeness
+ *
+ * cannot be called with relative paths anymore!
+ */
 FileData *blo_filedata_from_file(const char *filepath, struct BlendFileReadReport *reports);
 FileData *blo_filedata_from_memory(const void *mem,
                                    int memsize,
@@ -139,10 +144,28 @@ FileData *blo_filedata_from_memfile(struct MemFile *memfile,
                                     const struct BlendFileReadParams *params,
                                     struct BlendFileReadReport *reports);
 
+/**
+ * Lib linked proxy objects point to our local data, we need
+ * to clear that pointer before reading the undo memfile since
+ * the object might be removed, it is set again in reading
+ * if the local object still exists.
+ * This is only valid for local proxy objects though, linked ones should not be affected here.
+ */
 void blo_clear_proxy_pointers_from_lib(struct Main *oldmain);
 void blo_make_packed_pointer_map(FileData *fd, struct Main *oldmain);
+/**
+ * Set old main packed data to zero if it has been restored
+ * this works because freeing old main only happens after this call.
+ */
 void blo_end_packed_pointer_map(FileData *fd, struct Main *oldmain);
+/**
+ * Undo file support: add all library pointers in lookup.
+ */
 void blo_add_library_pointer_map(ListBase *old_mainlist, FileData *fd);
+/**
+ * Build a #GSet of old main (we only care about local data here,
+ * so we can do that after #blo_split_main() call.
+ */
 void blo_make_old_idmap_from_main(FileData *fd, struct Main *bmain);
 
 BHead *blo_read_asset_data_block(FileData *fd, BHead *bhead, struct AssetMetaData **r_asset_data);
@@ -157,23 +180,48 @@ BHead *blo_bhead_first(FileData *fd);
 BHead *blo_bhead_next(FileData *fd, BHead *thisblock);
 BHead *blo_bhead_prev(FileData *fd, BHead *thisblock);
 
+/**
+ * Warning! Caller's responsibility to ensure given bhead **is** an ID one!
+ */
 const char *blo_bhead_id_name(const FileData *fd, const BHead *bhead);
+/**
+ * Warning! Caller's responsibility to ensure given bhead **is** an ID one!
+ */
 struct AssetMetaData *blo_bhead_id_asset_data_address(const FileData *fd, const BHead *bhead);
 
 /* do versions stuff */
 
+/**
+ * Manipulates SDNA before calling #DNA_struct_get_compareflags,
+ * allowing us to rename structs and struct members.
+ *
+ * - This means older versions of Blender won't have access to this data **USE WITH CARE**.
+ * - These changes are applied on file load (run-time), similar to versioning for compatibility.
+ *
+ * \attention ONLY USE THIS KIND OF VERSIONING WHEN `dna_rename_defs.h` ISN'T SUFFICIENT.
+ */
 void blo_do_versions_dna(struct SDNA *sdna, const int versionfile, const int subversionfile);
 
 void blo_do_versions_oldnewmap_insert(struct OldNewMap *onm,
                                       const void *oldaddr,
                                       void *newaddr,
                                       int nr);
+/**
+ * Only library data.
+ */
 void *blo_do_versions_newlibadr(struct FileData *fd, const void *lib, const void *adr);
 void *blo_do_versions_newlibadr_us(struct FileData *fd, const void *lib, const void *adr);
 
+/**
+ * \note this version patch is intended for versions < 2.52.2,
+ * but was initially introduced in 2.27 already.
+ */
 void blo_do_version_old_trackto_to_constraints(struct Object *ob);
 void blo_do_versions_key_uidgen(struct Key *key);
 
+/**
+ * Patching #UserDef struct and Themes.
+ */
 void blo_do_versions_userdef(struct UserDef *userdef);
 
 void blo_do_versions_pre250(struct FileData *fd, struct Library *lib, struct Main *bmain);
@@ -193,6 +241,10 @@ void do_versions_after_linking_290(struct Main *bmain, struct ReportList *report
 void do_versions_after_linking_300(struct Main *bmain, struct ReportList *reports);
 void do_versions_after_linking_cycles(struct Main *bmain);
 
-/* This is rather unfortunate to have to expose this here, but better use that nasty hack in
- * do_version than readfile itself. */
+/**
+ * Direct data-blocks with global linking.
+ *
+ * \note This is rather unfortunate to have to expose this here,
+ * but better use that nasty hack in do_version than readfile itself.
+ */
 void *blo_read_get_new_globaldata_address(struct FileData *fd, const void *adr);
diff --git a/source/blender/blenloader/intern/undofile.c b/source/blender/blenloader/intern/undofile.c
index 62072cf7df5..dfa6135dac9 100644
--- a/source/blender/blenloader/intern/undofile.c
+++ b/source/blender/blenloader/intern/undofile.c
@@ -55,7 +55,6 @@
 
 /* **************** support for memory-write, for undo buffers *************** */
 
-/* not memfile itself */
 void BLO_memfile_free(MemFile *memfile)
 {
   MemFileChunk *chunk;
@@ -69,8 +68,6 @@ void BLO_memfile_free(MemFile *memfile)
   memfile->size = 0;
 }
 
-/* to keep list of memfiles consistent, 'first' is always first in list */
-/* result is that 'first' is being freed */
 void BLO_memfile_merge(MemFile *first, MemFile *second)
 {
   /* We use this mapping to store the memory buffers from second memfile chunks which are not owned
@@ -106,7 +103,6 @@ void BLO_memfile_merge(MemFile *first, MemFile *second)
   BLO_memfile_free(first);
 }
 
-/* Clear is_identical_future before adding next memfile. */
 void BLO_memfile_clear_future(MemFile *memfile)
 {
   LISTBASE_FOREACH (MemFileChunk *, chunk, &memfile->chunks) {
@@ -216,11 +212,6 @@ struct Main *BLO_memfile_main_get(struct MemFile *memfile,
   return bmain_undo;
 }
 
-/**
- * Saves .blend using undo buffer.
- *
- * \return success.
- */
 bool BLO_memfile_write_file(struct MemFile *memfile, const char *filename)
 {
   MemFileChunk *chunk;
diff --git a/source/blender/blenloader/intern/versioning_common.cc b/source/blender/blenloader/intern/versioning_common.cc
index 8ad948915ac..3deaaa040d6 100644
--- a/source/blender/blenloader/intern/versioning_common.cc
+++ b/source/blender/blenloader/intern/versioning_common.cc
@@ -61,11 +61,6 @@ ARegion *do_versions_add_region_if_not_found(ListBase *regionbase,
   return new_region;
 }
 
-/**
- * Rename if the ID doesn't exist.
- *
- * \return the ID (if found).
- */
 ID *do_versions_rename_id(Main *bmain,
                           const short id_type,
                           const char *name_src,
@@ -104,9 +99,6 @@ static void change_node_socket_name(ListBase *sockets, const char *old_name, con
   }
 }
 
-/**
- * Convert `SocketName.001` unique name format to `SocketName_001`. Previously both were used.
- */
 void version_node_socket_id_delim(bNodeSocket *socket)
 {
   StringRef name = socket->name;
@@ -180,9 +172,6 @@ bNodeSocket *version_node_add_socket_if_not_exist(bNodeTree *ntree,
   return nodeAddStaticSocket(ntree, node, in_out, type, subtype, identifier, name);
 }
 
-/**
- * Replace the ID name of all nodes in the tree with the given type with the new name.
- */
 void version_node_id(bNodeTree *ntree, const int node_type, const char *new_name)
 {
   LISTBASE_FOREACH (bNode *, node, &ntree->nodes) {
@@ -194,23 +183,6 @@ void version_node_id(bNodeTree *ntree, const int node_type, const char *new_name
   }
 }
 
-/**
- * Adjust animation data for newly added node sockets.
- *
- * Node sockets are addressed by their index (in their RNA path, and thus FCurves/drivers), and
- * thus when a new node is added in the middle of the list, existing animation data needs to be
- * adjusted.
- *
- * Since this is about animation data, it only concerns input sockets.
- *
- * \param node_tree_type: Node tree type that has these nodes, for example #NTREE_SHADER.
- * \param node_type: Node type to adjust, for example #SH_NODE_BSDF_PRINCIPLED.
- * \param socket_index_orig: The original index of the moved socket; when socket 4 moved to 6,
- * pass 4 here.
- * \param socket_index_offset: The offset of the nodes, so when socket 4 moved to 6,
- * pass 2 here.
- * \param total_number_of_sockets: The total number of sockets in the node.
- */
 void version_node_socket_index_animdata(Main *bmain,
                                         const int node_tree_type,
                                         const int node_type,
diff --git a/source/blender/blenloader/intern/versioning_common.h b/source/blender/blenloader/intern/versioning_common.h
index 3788d8f5595..0613484b754 100644
--- a/source/blender/blenloader/intern/versioning_common.h
+++ b/source/blender/blenloader/intern/versioning_common.h
@@ -34,6 +34,11 @@ struct ARegion *do_versions_add_region_if_not_found(struct ListBase *regionbase,
                                                     const char *name,
                                                     int link_after_region_type);
 
+/**
+ * Rename if the ID doesn't exist.
+ *
+ * \return the ID (if found).
+ */
 ID *do_versions_rename_id(Main *bmain,
                           const short id_type,
                           const char *name_src,
@@ -52,6 +57,23 @@ void version_node_output_socket_name(struct bNodeTree *ntree,
                                      const char *old_name,
                                      const char *new_name);
 
+/**
+ * Adjust animation data for newly added node sockets.
+ *
+ * Node sockets are addressed by their index (in their RNA path, and thus FCurves/drivers), and
+ * thus when a new node is added in the middle of the list, existing animation data needs to be
+ * adjusted.
+ *
+ * Since this is about animation data, it only concerns input sockets.
+ *
+ * \param node_tree_type: Node tree type that has these nodes, for example #NTREE_SHADER.
+ * \param node_type: Node type to adjust, for example #SH_NODE_BSDF_PRINCIPLED.
+ * \param socket_index_orig: The original index of the moved socket; when socket 4 moved to 6,
+ * pass 4 here.
+ * \param socket_index_offset: The offset of the nodes, so when socket 4 moved to 6,
+ * pass 2 here.
+ * \param total_number_of_sockets: The total number of sockets in the node.
+ */
 void version_node_socket_index_animdata(
     Main *bmain,
     int node_tree_type, /* NTREE_....., e.g. NTREE_SHADER */
@@ -60,8 +82,14 @@ void version_node_socket_index_animdata(
     int socket_index_offset,
     int total_number_of_sockets);
 
+/**
+ * Replace the ID name of all nodes in the tree with the given type with the new name.
+ */
 void version_node_id(struct bNodeTree *ntree, const int node_type, const char *new_name);
 
+/**
+ * Convert `SocketName.001` unique name format to `SocketName_001`. Previously both were used.
+ */
 void version_node_socket_id_delim(bNodeSocket *socket);
 
 struct bNodeSocket *version_node_add_socket_if_not_exist(struct bNodeTree *ntree,
diff --git a/source/blender/blenloader/intern/versioning_defaults.c b/source/blender/blenloader/intern/versioning_defaults.c
index fa61b1ca6cd..a5c44ea711b 100644
--- a/source/blender/blenloader/intern/versioning_defaults.c
+++ b/source/blender/blenloader/intern/versioning_defaults.c
@@ -367,15 +367,6 @@ static void blo_update_defaults_scene(Main *bmain, Scene *scene)
   }
 }
 
-/**
- * Update defaults in startup.blend, without having to save and embed the file.
- * This function can be emptied each time the startup.blend is updated.
- *
- * \note Screen data may be cleared at this point, this will happen in the case
- * an app-template's data needs to be versioned when read-file is called with "Load UI" disabled.
- * Versioning the screen data can be safely skipped without "Load UI" since the screen data
- * will have been versioned when it was first loaded.
- */
 void BLO_update_defaults_startup_blend(Main *bmain, const char *app_template)
 {
   /* For all app templates. */
diff --git a/source/blender/blenloader/intern/versioning_dna.c b/source/blender/blenloader/intern/versioning_dna.c
index aee54b94833..0a97eedb993 100644
--- a/source/blender/blenloader/intern/versioning_dna.c
+++ b/source/blender/blenloader/intern/versioning_dna.c
@@ -29,16 +29,6 @@
 #include "BLO_readfile.h"
 #include "readfile.h"
 
-/**
- * Manipulates SDNA before calling #DNA_struct_get_compareflags,
- * allowing us to rename structs and struct members.
- *
- * - This means older versions of Blender won't have access to this data **USE WITH CARE**.
- *
- * - These changes are applied on file load (run-time), similar to versioning for compatibility.
- *
- * \attention ONLY USE THIS KIND OF VERSIONING WHEN `dna_rename_defs.h` ISN'T SUFFICIENT.
- */
 void blo_do_versions_dna(SDNA *sdna, const int versionfile, const int subversionfile)
 {
 #define DNA_VERSION_ATLEAST(ver, subver) \
diff --git a/source/blender/blenloader/intern/versioning_legacy.c b/source/blender/blenloader/intern/versioning_legacy.c
index 37bf4898cb3..2fceb42262e 100644
--- a/source/blender/blenloader/intern/versioning_legacy.c
+++ b/source/blender/blenloader/intern/versioning_legacy.c
@@ -461,8 +461,6 @@ static void do_version_constraints_245(ListBase *lb)
   }
 }
 
-/* NOTE: this version patch is intended for versions < 2.52.2,
- * but was initially introduced in 2.27 already. */
 void blo_do_version_old_trackto_to_constraints(Object *ob)
 {
   /* create new trackto constraint from the relationship */
diff --git a/source/blender/blenloader/intern/versioning_userdef.c b/source/blender/blenloader/intern/versioning_userdef.c
index 0e5e0b76f43..3338d2f658c 100644
--- a/source/blender/blenloader/intern/versioning_userdef.c
+++ b/source/blender/blenloader/intern/versioning_userdef.c
@@ -399,7 +399,6 @@ static bool keymap_item_has_invalid_wm_context_data_path(wmKeyMapItem *kmi,
   return false;
 }
 
-/* patching UserDef struct and Themes */
 void blo_do_versions_userdef(UserDef *userdef)
 {
   /* #UserDef & #Main happen to have the same struct member. */
diff --git a/source/blender/blenloader/intern/writefile.c b/source/blender/blenloader/intern/writefile.c
index 15ed3224023..f8f5dab8797 100644
--- a/source/blender/blenloader/intern/writefile.c
+++ b/source/blender/blenloader/intern/writefile.c
@@ -1312,9 +1312,6 @@ static bool do_history(const char *name, ReportList *reports)
 /** \name File Writing (Public)
  * \{ */
 
-/**
- * \return Success.
- */
 bool BLO_write_file(Main *mainvar,
                     const char *filepath,
                     const int write_flags,
@@ -1453,9 +1450,6 @@ bool BLO_write_file(Main *mainvar,
   return 1;
 }
 
-/**
- * \return Success.
- */
 bool BLO_write_file_mem(Main *mainvar, MemFile *compare, MemFile *current, int write_flags)
 {
   bool use_userdef = false;
@@ -1578,9 +1572,6 @@ void BLO_write_float3_array(BlendWriter *writer, uint num, const float *data_ptr
   BLO_write_raw(writer, sizeof(float[3]) * (size_t)num, data_ptr);
 }
 
-/**
- * Write a null terminated string.
- */
 void BLO_write_string(BlendWriter *writer, const char *data_ptr)
 {
   if (data_ptr != NULL) {
@@ -1588,10 +1579,6 @@ void BLO_write_string(BlendWriter *writer, const char *data_ptr)
   }
 }
 
-/**
- * Sometimes different data is written depending on whether the file is saved to disk or used for
- * undo. This function returns true when the current file-writing is done for undo.
- */
 bool BLO_write_is_undo(BlendWriter *writer)
 {
   return writer->wd->use_memfile;