1 files changed, 39 insertions, 9 deletions

diff --git a/source/blender/blenkernel/BKE_packedFile.h b/source/blender/blenkernel/BKE_packedFile.h
index 8cb0c78d9aa..87a46f5f888 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,
@@ -105,25 +120,40 @@ int BKE_packedfile_write_to_file(struct ReportList *reports,
                                  const char *ref_file_name,
                                  const char *filename,
                                  struct PackedFile *pf,
-                                 const bool guimode);
+                                 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 1 if there's a packed file */
-bool BKE_packedfile_id_check(struct ID *id);
-/* ID should be not NULL, throws error when ID is Library */
+/**
+ * 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.
+ */
 void BKE_packedfile_id_unpack(struct Main *bmain,
                               struct ID *id,
                               struct ReportList *reports,