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

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 42 insertions, 1 deletions

diff --git a/source/blender/blenkernel/BKE_blendfile.h b/source/blender/blenkernel/BKE_blendfile.h
index 3e0a343a766..b3211b1dbbc 100644
--- a/source/blender/blenkernel/BKE_blendfile.h
+++ b/source/blender/blenkernel/BKE_blendfile.h
@@ -33,6 +33,14 @@ struct ReportList;
 struct UserDef;
 struct bContext;
 
+/**
+ * Shared setup function that makes the data from `bfd` into the current blend file,
+ * replacing the contents of #G.main.
+ * This uses the bfd #BKE_blendfile_read and similarly named functions.
+ *
+ * This is done in a separate step so the caller may perform actions after it is known the file
+ * loaded correctly but before the file replaces the existing blend file contents.
+ */
 void BKE_blendfile_read_setup_ex(struct bContext *C,
                                  struct BlendFileData *bfd,
                                  const struct BlendFileReadParams *params,
@@ -46,28 +54,56 @@ void BKE_blendfile_read_setup(struct bContext *C,
                               const struct BlendFileReadParams *params,
                               struct BlendFileReadReport *reports);
 
+/**
+ * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL.
+ */
 struct BlendFileData *BKE_blendfile_read(const char *filepath,
                                          const struct BlendFileReadParams *params,
                                          struct BlendFileReadReport *reports);
 
+/**
+ * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL.
+ */
 struct BlendFileData *BKE_blendfile_read_from_memory(const void *filebuf,
                                                      int filelength,
                                                      const struct BlendFileReadParams *params,
                                                      struct ReportList *reports);
 
+/**
+ * \return Blend file data, this must be passed to #BKE_blendfile_read_setup when non-NULL.
+ * \note `memfile` is the undo buffer.
+ */
 struct BlendFileData *BKE_blendfile_read_from_memfile(struct Main *bmain,
                                                       struct MemFile *memfile,
                                                       const struct BlendFileReadParams *params,
                                                       struct ReportList *reports);
+/**
+ * Utility to make a file 'empty' used for startup to optionally give an empty file.
+ * Handy for tests.
+ */
 void BKE_blendfile_read_make_empty(struct bContext *C);
 
+/**
+ * Only read the #UserDef from a .blend.
+ */
 struct UserDef *BKE_blendfile_userdef_read(const char *filepath, struct ReportList *reports);
 struct UserDef *BKE_blendfile_userdef_read_from_memory(const void *filebuf,
                                                        int filelength,
                                                        struct ReportList *reports);
 struct UserDef *BKE_blendfile_userdef_from_defaults(void);
 
+/**
+ * Only write the #UserDef in a `.blend`.
+ * \return success.
+ */
 bool BKE_blendfile_userdef_write(const char *filepath, struct ReportList *reports);
+/**
+ * Only write the #UserDef in a `.blend`, merging with the existing blend file.
+ * \return success.
+ *
+ * \note In the future we should re-evaluate user preferences,
+ * possibly splitting out system/hardware specific preferences.
+ */
 bool BKE_blendfile_userdef_write_app_template(const char *filepath, struct ReportList *reports);
 
 bool BKE_blendfile_userdef_write_all(struct ReportList *reports);
@@ -81,9 +117,14 @@ bool BKE_blendfile_workspace_config_write(struct Main *bmain,
                                           struct ReportList *reports);
 void BKE_blendfile_workspace_config_data_free(struct WorkspaceConfigFileData *workspace_config);
 
-/* partial blend file writing */
+/* Partial blend file writing. */
+
 void BKE_blendfile_write_partial_tag_ID(struct ID *id, bool set);
 void BKE_blendfile_write_partial_begin(struct Main *bmain_src);
+/**
+ * \param remap_mode: Choose the kind of path remapping or none #eBLO_WritePathRemap.
+ * \return Success.
+ */
 bool BKE_blendfile_write_partial(struct Main *bmain_src,
                                  const char *filepath,
                                  const int write_flags,