improve documentation

2 files changed, 92 insertions, 37 deletions

diff --git a/source/blender/blenloader/BLO_read_write.h b/source/blender/blenloader/BLO_read_write.h
index 064d7b3cd78..e15ec830178 100644
--- a/source/blender/blenloader/BLO_read_write.h
+++ b/source/blender/blenloader/BLO_read_write.h
@@ -14,6 +14,29 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/** \file
+ * \ingroup blenloader
+ *
+ * API that allows different parts of Blender to define what data is stored in .blend files.
+ *
+ * Four callbacks have to be provided to fully implement .blend I/O for a piece of data. One of
+ * those is related to file writing and three for file reading. Reading requires multiple
+ * callbacks, due to the way linking between files works.
+ *
+ * Quick description of the individual callbacks:
+ *  - Blend Write: Define which structs and memory buffers are saved.
+ *  - Blend Read Data: Loads structs and memory buffers from file and updates pointers them.
+ *  - Blend Read Lib: Updates pointers to ID data blocks.
+ *  - Blend Expand: Defines which other data blocks should be loaded (possibly from other files).
+ *
+ * Each of these callbacks uses a different API functions.
+ *
+ * Some parts of Blender, e.g. modifiers, don't require you to implement all four callbacks.
+ * Instead only the first two are necessary. The other two are handled by general ID management. In
+ * the future, we might want to get rid of those two callbacks entirely, but for now they are
+ * necessary.
+ */
+
 #ifndef __BLO_READ_WRITE_H__
 #define __BLO_READ_WRITE_H__
 
@@ -28,70 +51,90 @@ typedef struct BlendDataReader BlendDataReader;
 typedef struct BlendLibReader BlendLibReader;
 typedef struct BlendExpander BlendExpander;
 
+/* ************************************************ */
 /* API for file writing.
- **********************************************/
-
-/**
- * When NULL is passed as data_ptr, nothing is done.
+ *
+ * Most functions fall into one of two categories. Either they write a DNA struct or a raw memory
+ * buffer to the .blend file.
+ *
+ * It is safe to pass NULL as data_ptr. In this case nothing will be stored.
+ *
+ * DNA Struct Writing
+ * ------------------
+ *
+ * Functions dealing with DNA structs begin with BLO_write_struct_*.
+ *
+ * DNA struct types can be identified in different ways:
+ *  - Run-time Name: The name is provided as const char *.
+ *  - Compile-time Name: The name is provided at compile time. This can be more efficient. Note
+ *      that this optimization is not implemented currently.
+ *  - Struct ID: Every DNA struct type has an integer ID that can be queried with
+ *      BLO_get_struct_id_by_name. Providing this ID can be a useful optimization when many structs
+ *      of the same type are stored AND if those structs are not in a continuous array.
+ *
+ * Often only a single instance of a struct is written at once. However, sometimes it is necessary
+ * to write arrays or linked lists. Separate functions for that are provided as well.
+ *
+ * There is a special macro for writing id structs: BLO_write_id_struct. Those are handled
+ * differently from other structs.
+ *
+ * Raw Data Writing
+ * ----------------
+ *
+ * At the core there is BLO_write_raw, which can write arbitrary memory buffers to the file. 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.
  */
 
-/**
- * Write a single DNA struct to the file.
- */
+/* 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) BLO_get_struct_id_by_name(writer, #struct_name)
+
+/* 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 struct array. */
 void BLO_write_struct_array_by_name(BlendWriter *writer,
                                     const char *struct_name,
                                     int array_size,
                                     const void *data_ptr);
-void BLO_write_struct_by_id_at_address(BlendWriter *writer,
-                                       int struct_data,
-                                       const void *data_ptr,
-                                       const void *address);
-
-void BLO_write_struct_by_id(BlendWriter *writer, int struct_id, const void *data_ptr);
 void BLO_write_struct_array_by_id(BlendWriter *writer,
                                   int struct_id,
                                   int array_size,
                                   const void *data_ptr);
+#define BLO_write_struct_array(writer, struct_name, array_size, data_ptr) \
+  BLO_write_struct_array_by_id( \
+      writer, BLO_get_struct_id(writer, struct_name), array_size, data_ptr)
+
+/* Write struct list. */
+void BLO_write_struct_list_by_name(BlendWriter *writer,
+                                   const char *struct_name,
+                                   struct ListBase *list);
 void BLO_write_struct_list_by_id(BlendWriter *writer, int struct_id, struct ListBase *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. */
 void blo_write_id_struct(BlendWriter *writer,
                          int struct_id,
                          const void *id_address,
                          const struct ID *id);
-
-int BLO_get_struct_id_by_name(BlendWriter *writer, const char *struct_name);
-#define BLO_get_struct_id(writer, struct_name) BLO_get_struct_id_by_name(writer, #struct_name)
-
-#define BLO_write_struct(writer, struct_name, data_ptr) \
-  BLO_write_struct_by_id(writer, BLO_get_struct_id(writer, struct_name), data_ptr)
-#define BLO_write_struct_array(writer, struct_name, array_size, data_ptr) \
-  BLO_write_struct_array_by_id( \
-      writer, BLO_get_struct_id(writer, struct_name), array_size, data_ptr)
-#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)
 #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 the data in the given memory buffer to the file. The pointer is used to identify the
- * buffer when the file is loaded.
- */
+/* Write raw data. */
 void BLO_write_raw(BlendWriter *writer, int size_in_bytes, const void *data_ptr);
-
-/**
- * Wrappers around BLO_write_raw that are more convenient in many cases.
- */
 void BLO_write_int32_array(BlendWriter *writer, int size, const int32_t *data_ptr);
 void BLO_write_uint32_array(BlendWriter *writer, int size, const uint32_t *data_ptr);
 void BLO_write_float_array(BlendWriter *writer, int size, const float *data_ptr);
 void BLO_write_float3_array(BlendWriter *writer, int size, const float *data_ptr);
-void BLO_write_string(BlendWriter *writer, const char *str);
+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.
- */
+/* Misc. */
 bool BLO_write_is_undo(BlendWriter *writer);
 
 /* API for data pointer reading.
diff --git a/source/blender/blenloader/intern/writefile.c b/source/blender/blenloader/intern/writefile.c
index c064087fbaf..5fb15d663dc 100644
--- a/source/blender/blenloader/intern/writefile.c
+++ b/source/blender/blenloader/intern/writefile.c
@@ -4109,6 +4109,11 @@ void BLO_write_struct_list_by_id(BlendWriter *writer, int struct_id, ListBase *l
   writelist_nr(writer->wd, DATA, struct_id, list);
 }
 
+void BLO_write_struct_list_by_name(BlendWriter *writer, const char *struct_name, ListBase *list)
+{
+  BLO_write_struct_list_by_id(writer, BLO_get_struct_id_by_name(writer, struct_name), list);
+}
+
 void blo_write_id_struct(BlendWriter *writer, int struct_id, const void *id_address, const ID *id)
 {
   writestruct_at_address_nr(writer->wd, GS(id->name), struct_id, 1, id_address, id);
@@ -4141,6 +4146,9 @@ void BLO_write_float3_array(BlendWriter *writer, int size, const float *data_ptr
   BLO_write_raw(writer, sizeof(float) * 3 * size, data_ptr);
 }
 
+/**
+ * Write a null terminated string.
+ */
 void BLO_write_string(BlendWriter *writer, const char *str)
 {
   if (str != NULL) {
@@ -4148,6 +4156,10 @@ void BLO_write_string(BlendWriter *writer, const char *str)
   }
 }
 
+/**
+ * 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;