[ostree] core: Add a comment header about the format

[Colin Walters <walters src gnome org>]

commit 61773f6ca4f6029be016d573fcc661c6e2bfc63e
Author: Colin Walters <walters verbum org>
Date:   Wed Aug 14 17:27:30 2013 +0200

    core: Add a comment header about the format
    
    This should probably be a design document or something, but this is
    useful for now.

 src/libostree/ostree-core.h |   17 +++++++++++++++++
 1 files changed, 17 insertions(+), 0 deletions(-)
---
diff --git a/src/libostree/ostree-core.h b/src/libostree/ostree-core.h
index cc940e6..6f89265 100644
--- a/src/libostree/ostree-core.h
+++ b/src/libostree/ostree-core.h
@@ -26,6 +26,23 @@
 
 G_BEGIN_DECLS
 
+/**
+ * These functions implement repository-independent algorithms for
+ * operating on the core OSTree data formats, such as converting
+ * #GFileInfo into a #GVariant.
+ *
+ * There are 4 types of objects; file, dirmeta, tree, and commit.  The
+ * last 3 are metadata, and the file object is the only content object
+ * type.
+ *
+ * All metadata objects are stored as #GVariant (big endian).  The
+ * rationale for this is the same as that of the ext{2,3,4} family of
+ * filesystems; most developers will be using LE, and so it's better
+ * to continually test the BE->LE swap.
+ *
+ * The file object is a custom format in order to support streaming.
+ */
+
 #define OSTREE_MAX_METADATA_SIZE (1 << 26)
 
 #define OSTREE_MAX_RECURSION (256)