[Bf-blender-cvs] [fdfd87f] master: Docs: comment BHead.code values

[Campbell Barton]

Commit: fdfd87f2f4e656b2292683c923156dd9ea96512b
Author: Campbell Barton
Date:   Fri Aug 14 17:30:32 2015 +1000
Branches: master
https://developer.blender.org/rBfdfd87f2f4e656b2292683c923156dd9ea96512b

Docs: comment BHead.code values

===================================================================

M	source/blender/blenloader/BLO_blend_defs.h
M	source/blender/makesdna/DNA_ID.h

===================================================================

diff --git a/source/blender/blenloader/BLO_blend_defs.h b/source/blender/blenloader/BLO_blend_defs.h
index 8005be1..34a881b 100644
--- a/source/blender/blenloader/BLO_blend_defs.h
+++ b/source/blender/blenloader/BLO_blend_defs.h
@@ -34,14 +34,45 @@
 #  define BLEND_MAKE_ID(a, b, c, d) ( (int)(d) << 24 | (int)(c) << 16 | (b) << 8 | (a) )
 #endif
 
-#define DATA BLEND_MAKE_ID('D', 'A', 'T', 'A')
-#define GLOB BLEND_MAKE_ID('G', 'L', 'O', 'B')
-
-#define DNA1 BLEND_MAKE_ID('D', 'N', 'A', '1')
-#define TEST BLEND_MAKE_ID('T', 'E', 'S', 'T') /* used as preview between 'REND' and 'GLOB' */
-#define REND BLEND_MAKE_ID('R', 'E', 'N', 'D')
-#define USER BLEND_MAKE_ID('U', 'S', 'E', 'R')
-
-#define ENDB BLEND_MAKE_ID('E', 'N', 'D', 'B')
+/**
+ * Codes used for #BHead.code.
+ *
+ * These coexist with ID codes such as #ID_OB, #ID_SCE ... etc.
+ */
+enum {
+	/**
+	 * Arbitrary allocated memory
+	 * (owned by #ID's, or will leak on exit)
+	 */
+	DATA = BLEND_MAKE_ID('D', 'A', 'T', 'A'),
+	/**
+	 * Used for #Global struct.
+	 */
+	GLOB = BLEND_MAKE_ID('G', 'L', 'O', 'B'),
+	/**
+	 * Used for storing the encoded SDNA string
+	 * (decoded into an #SDNA on load).
+	 */
+	DNA1 = BLEND_MAKE_ID('D', 'N', 'A', '1'),
+	/**
+	 * Used as preview between #REND and #GLOB,
+	 * (ignored for regular file reading)
+	 */
+	TEST = BLEND_MAKE_ID('T', 'E', 'S', 'T'),
+	/**
+	 * Used for #RenderInfo, basic Scene and frame range info,
+	 * can be easily read by other applications without writing a full blend file parser.
+	 */
+	REND = BLEND_MAKE_ID('R', 'E', 'N', 'D'),
+	/**
+	 * Used for #UserDef, (user-preferences data).
+	 * (written to #BLENDER_STARTUP_FILE & #BLENDER_USERPREF_FILE).
+	 */
+	USER = BLEND_MAKE_ID('U', 'S', 'E', 'R'),
+	/**
+	 * Terminate reading (no data).
+	 */
+	ENDB = BLEND_MAKE_ID('E', 'N', 'D', 'B'),
+};
 
 #endif  /* __BLO_BLEND_DEFS_H__ */
diff --git a/source/blender/makesdna/DNA_ID.h b/source/blender/makesdna/DNA_ID.h
index 88e728c..429679f 100644
--- a/source/blender/makesdna/DNA_ID.h
+++ b/source/blender/makesdna/DNA_ID.h
@@ -201,7 +201,12 @@ typedef struct PreviewImage {
 #  define MAKE_ID2(c, d)  ((d) << 8 | (c))
 #endif
 
-/* ID from database */
+/**
+ * ID from database.
+ *
+ * Written to #BHead.code (for file IO)
+ * and the first 2 bytes of #ID.name (for runtime checks, see #GS macro).
+ */
 #define ID_SCE		MAKE_ID2('S', 'C') /* Scene */
 #define ID_LI		MAKE_ID2('L', 'I') /* Library */
 #define ID_OB		MAKE_ID2('O', 'B') /* Object */