From c3121b52bca027d737dd9062a89412977b736a8c Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Sat, 17 Aug 2013 08:21:04 -0400
Subject: [PATCH] libostree: Document more core macros

---
 doc/libostree-sections.txt  |  1 -
 src/libostree/ostree-core.c | 17 ++++++--
 src/libostree/ostree-core.h | 85 +++++++++++++++++++++++--------------
 3 files changed, 67 insertions(+), 36 deletions(-)

diff --git a/doc/libostree-sections.txt b/doc/libostree-sections.txt
index 7fb2b0c1..2e7559ff 100644
--- a/doc/libostree-sections.txt
+++ b/doc/libostree-sections.txt
@@ -2,7 +2,6 @@
 <FILE>libostree-core</FILE>
 OSTREE_MAX_METADATA_SIZE
 OSTREE_MAX_RECURSION
-OSTREE_EMPTY_STRING_SHA256
 OstreeObjectType
 OSTREE_OBJECT_TYPE_IS_META
 OSTREE_OBJECT_TYPE_LAST
diff --git a/src/libostree/ostree-core.c b/src/libostree/ostree-core.c
index 06631794..da525bb0 100644
--- a/src/libostree/ostree-core.c
+++ b/src/libostree/ostree-core.c
@@ -40,9 +40,20 @@
  * @title: Core repository-independent functions
  * @short_description: Create, validate, and convert core data types
  *
- * These functions make up the core data manipulation functions of
- * OSTree, such as serializing/deserializing metadata, converting
- * between different types of checksums, and validating input.
+ * 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.
  */
 
 const GVariantType *
diff --git a/src/libostree/ostree-core.h b/src/libostree/ostree-core.h
index e2eb7a78..44933976 100644
--- a/src/libostree/ostree-core.h
+++ b/src/libostree/ostree-core.h
@@ -26,29 +26,27 @@
 
 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.
- */
 
+/**
+ * OSTREE_MAX_METADATA_SIZE:
+ * 
+ * Maximum permitted size in bytes of metadata objects.
+ */
 #define OSTREE_MAX_METADATA_SIZE (1 << 26)
 
+/**
+ * OSTREE_MAX_RECURSION:
+ * 
+ * Maximum depth of metadata.
+ */
 #define OSTREE_MAX_RECURSION (256)
 
-#define OSTREE_EMPTY_STRING_SHA256 "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
-
+/**
+ * OstreeObjectType:
+ *
+ * Enumeration for core object types; %OSTREE_OBJECT_TYPE_FILE is for
+ * content, the other types are metadata.
+ */
 typedef enum {
   OSTREE_OBJECT_TYPE_FILE = 1,      /* .file */
   OSTREE_OBJECT_TYPE_DIR_TREE = 2,  /* .dirtree */
@@ -56,26 +54,43 @@ typedef enum {
   OSTREE_OBJECT_TYPE_COMMIT = 4     /* .commit */
 } OstreeObjectType;
 
+/**
+ * OSTREE_OBJECT_TYPE_IS_META:
+ *
+ * Returns: %TRUE if object type is metadata
+ */
 #define OSTREE_OBJECT_TYPE_IS_META(t) (t >= 2 && t <= 4)
+/**
+ * OSTREE_OBJECT_TYPE_LAST:
+ *
+ * Last valid object type; use this to validate ranges.
+ */
 #define OSTREE_OBJECT_TYPE_LAST OSTREE_OBJECT_TYPE_COMMIT
 
 
-/*
- * file objects:
- * <BE guint32 containing variant length>
+/**
+ * OSTREE_FILE_HEADER_GVARIANT_FORMAT:
+ *
+ * File objects are stored as a stream, with one #GVariant header,
+ * followed by content.
+ * 
+ * The file header is of the following form:
+ *
+ * &lt;BE guint32 containing variant length&gt;
  * u - uid
  * u - gid
  * u - mode
  * u - rdev
  * s - symlink target 
  * a(ayay) - xattrs
- * ---
- * data
+ *
+ * Then the rest of the stream is data.
  */
 #define OSTREE_FILE_HEADER_GVARIANT_FORMAT G_VARIANT_TYPE ("(uuuusa(ayay))")
 
-/*
- * dirmeta objects:
+/**
+ * OSTREE_DIRMETA_GVARIANT_FORMAT:
+ *
  * u - uid
  * u - gid
  * u - mode
@@ -83,15 +98,17 @@ typedef enum {
  */
 #define OSTREE_DIRMETA_GVARIANT_FORMAT G_VARIANT_TYPE ("(uuua(ayay))")
 
-/*
- * Tree objects:
+/**
+ * OSTREE_TREE_GVARIANT_FORMAT:
+ *
  * a(say) - array of (filename, checksum) for files
  * a(sayay) - array of (dirname, tree_checksum, meta_checksum) for directories
  */
 #define OSTREE_TREE_GVARIANT_FORMAT G_VARIANT_TYPE ("(a(say)a(sayay))")
 
-/*
- * Commit objects:
+/**
+ * OSTREE_COMMIT_GVARIANT_FORMAT:
+ *
  * a{sv} - Metadata
  * ay - parent checksum (empty string for initial)
  * a(say) - Related objects
@@ -103,9 +120,13 @@ typedef enum {
  */
 #define OSTREE_COMMIT_GVARIANT_FORMAT G_VARIANT_TYPE ("(a{sv}aya(say)sstayay)")
 
-/*
- * filez objects:
- * <BE guint32 containing variant length>
+/**
+ * OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT:
+ *
+ * This is a variation on %OSTREE_FILE_HEADER_GVARIANT_FORMAT, used for
+ * storing zlib-compressed content objects.
+ *
+ * &lt;BE guint32 containing variant length&gt;
  * t - size
  * u - uid
  * u - gid