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, 37 insertions, 7 deletions

diff --git a/source/blender/blenkernel/BKE_packedFile.h b/source/blender/blenkernel/BKE_packedFile.h
index 8ddf77e3d49..e3deff9d8fa 100644
--- a/source/blender/blenkernel/BKE_packedFile.h
+++ b/source/blender/blenkernel/BKE_packedFile.h
@@ -57,17 +57,32 @@ enum ePF_FileStatus {
   PF_ASK = 10,
 };
 
-/* pack */
+/* Pack. */
+
 struct PackedFile *BKE_packedfile_duplicate(const struct PackedFile *pf_src);
 struct PackedFile *BKE_packedfile_new(struct ReportList *reports,
                                       const char *filename,
                                       const char *basepath);
 struct PackedFile *BKE_packedfile_new_from_memory(void *mem, int memlen);
 
+/**
+ * No libraries for now.
+ */
 void BKE_packedfile_pack_all(struct Main *bmain, struct ReportList *reports, bool verbose);
 void BKE_packedfile_pack_all_libraries(struct Main *bmain, struct ReportList *reports);
 
-/* unpack */
+/* Unpack. */
+
+/**
+ * #BKE_packedfile_unpack_to_file() looks at the existing files (abs_name, local_name)
+ * and a packed file.
+ *
+ * It returns a char *to the existing file name / new file name or NULL when
+ * there was an error or when the user decides to cancel the operation.
+ *
+ * \warning 'abs_name' may be relative still! (use a "//" prefix)
+ * be sure to run #BLI_path_abs on it first.
+ */
 char *BKE_packedfile_unpack_to_file(struct ReportList *reports,
                                     const char *ref_file_name,
                                     const char *abs_name,
@@ -107,23 +122,38 @@ int BKE_packedfile_write_to_file(struct ReportList *reports,
                                  struct PackedFile *pf,
                                  const bool guimode);
 
-/* free */
+/* Free. */
+
 void BKE_packedfile_free(struct PackedFile *pf);
 
-/* info */
+/* Info. */
+
 int BKE_packedfile_count_all(struct Main *bmain);
+/**
+ * This function compares a packed file to a 'real' file.
+ * It returns an integer indicating if:
+ *
+ * - #PF_EQUAL:     the packed file and original file are identical.
+ * - #PF_DIFFERENT: the packed file and original file differ.
+ * - #PF_NOFILE:    the original file doesn't exist.
+ */
 enum ePF_FileCompare BKE_packedfile_compare_to_file(const char *ref_file_name,
                                                     const char *filename,
                                                     struct PackedFile *pf);
 
-/* read */
+/* Read. */
+
 int BKE_packedfile_seek(struct PackedFile *pf, int offset, int whence);
 void BKE_packedfile_rewind(struct PackedFile *pf);
 int BKE_packedfile_read(struct PackedFile *pf, void *data, int size);
 
-/* ID should be not NULL, return true if there's a packed file */
+/**
+ * ID should be not NULL, return true if there's a packed file.
+ */
 bool BKE_packedfile_id_check(const struct ID *id);
-/* ID should be not NULL, throws error when ID is Library */
+/**
+ * ID should be not NULL, throws error when ID is Library.
+ */
 void BKE_packedfile_id_unpack(struct Main *bmain,
                               struct ID *id,
                               struct ReportList *reports,