doc: more wip on iter docs

mwhittaker · May 29, 2014 · dde5fb4 · dde5fb4
1 parent c2a1ed5
commit dde5fb4
Show file tree

Hide file tree

Showing 19 changed files with 106 additions and 43 deletions.
diff --git a/doc/bson_iter_int32.page b/doc/bson_iter_int32.page
@@ -12,7 +12,11 @@
 
   <section id="synopsis">
     <title>Synopsis</title>
-    <synopsis><code mime="text/x-csrc"><![CDATA[int32_t
+    <synopsis><code mime="text/x-csrc"><![CDATA[
+#define BSON_ITER_HOLDS_INT32(iter) \
+   (bson_iter_type ((iter)) == BSON_TYPE_INT32)
+
+int32_t
 bson_iter_int32 (const bson_iter_t *iter);
 ]]></code></synopsis>
   </section>
@@ -26,11 +30,11 @@ bson_iter_int32 (const bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Fetches the value from a BSON_TYPE_INT32 element. You should verify that the field is a BSON_TYPE_INT32 field before calling this function.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A 32-bit integer.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_int64.page b/doc/bson_iter_int64.page
@@ -12,7 +12,11 @@
 
   <section id="synopsis">
     <title>Synopsis</title>
-    <synopsis><code mime="text/x-csrc"><![CDATA[int64_t
+    <synopsis><code mime="text/x-csrc"><![CDATA[
+#define BSON_ITER_HOLDS_INT64(iter) \
+   (bson_iter_type ((iter)) == BSON_TYPE_INT64)
+
+int64_t
 bson_iter_int64 (const bson_iter_t *iter);
 ]]></code></synopsis>
   </section>
@@ -26,11 +30,11 @@ bson_iter_int64 (const bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Fetches the value from a BSON_TYPE_INT64 field. You should verify that this is a BSON_TYPE_INT64 field before calling this function.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A 64-bit integer.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_key.page b/doc/bson_iter_key.page
@@ -26,11 +26,11 @@ bson_iter_key (const bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Fetches the key for the current element observed by <code>iter</code>.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A string which should not be modified or freed.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_next.page b/doc/bson_iter_next.page
@@ -26,11 +26,11 @@ bson_iter_next (bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Advances <code>iter</code> to the next element in the document if one exists.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>true if <code>iter</code> was advanced, otherwise false and <code>iter</code> should be considered invalid.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_oid.page b/doc/bson_iter_oid.page
@@ -12,7 +12,11 @@
 
   <section id="synopsis">
     <title>Synopsis</title>
-    <synopsis><code mime="text/x-csrc"><![CDATA[const bson_oid_t *
+    <synopsis><code mime="text/x-csrc"><![CDATA[
+#define BSON_ITER_HOLDS_OID(iter) \
+   (bson_iter_type ((iter)) == BSON_TYPE_OID)
+
+const bson_oid_t *
 bson_iter_oid (const bson_iter_t *iter);
 ]]></code></synopsis>
   </section>
@@ -26,11 +30,11 @@ bson_iter_oid (const bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Fetches the <link xref="bson_oid_t">bson_oid_t</link> for a BSON_TYPE_OID element. You should verify it is an element of type BSON_TYPE_OID before calling this function.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A <link xref="bson_oid_t">bson_oid_t</link> that should not be modified or freed.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_overwrite_bool.page b/doc/bson_iter_overwrite_bool.page
@@ -22,13 +22,15 @@ bson_iter_overwrite_bool (bson_iter_t *iter,
     <title>Parameters</title>
     <table>
       <tr><td><p>iter</p></td><td><p>A <link xref="bson_iter_t">bson_iter_t</link>.</p></td></tr>
-      <tr><td><p>value</p></td><td><p>A (null).</p></td></tr>
+      <tr><td><p>value</p></td><td><p>A bool containing the new value.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The <code>bson_iter_overwrite_bool()</code> function shall overwrite the contents of a BSON_TYPE_BOOL element in place.</p>
+    <p>This may only be done when the underlying bson document allows mutation.</p>
+    <p>It is a programming error to call this function when <code>iter</code> is not obvserving an element of type BSON_TYPE_BOOL.</p>
   </section>
 
 </page>
diff --git a/doc/bson_iter_overwrite_double.page b/doc/bson_iter_overwrite_double.page
@@ -22,13 +22,15 @@ bson_iter_overwrite_double (bson_iter_t *iter,
     <title>Parameters</title>
     <table>
       <tr><td><p>iter</p></td><td><p>A <link xref="bson_iter_t">bson_iter_t</link>.</p></td></tr>
-      <tr><td><p>value</p></td><td><p>A (null).</p></td></tr>
+      <tr><td><p>value</p></td><td><p>The new double value.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_overwrite_double()_ function shall overwrite the contents of a BSON_TYPE_DOUBLE element in place.</p>
+    <p>This may only be done when the underlying bson document allows mutation.</p>
+    <p>It is a programming error to call this function when _iter_ is not obvserving an element of type BSON_TYPE_DOUBLE.</p>
   </section>
 
 </page>
diff --git a/doc/bson_iter_overwrite_int32.page b/doc/bson_iter_overwrite_int32.page
@@ -28,7 +28,9 @@ bson_iter_overwrite_int32 (bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_overwrite_int32()_ function shall overwrite the contents of a BSON_TYPE_INT32 element in place.</p>
+    <p>This may only be done when the underlying bson document allows mutation.</p>
+    <p>It is a programming error to call this function when _iter_ is not obvserving an element of type BSON_TYPE_BOOL.</p>
   </section>
 
 </page>
diff --git a/doc/bson_iter_overwrite_int64.page b/doc/bson_iter_overwrite_int64.page
@@ -28,7 +28,9 @@ bson_iter_overwrite_int64 (bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_overwrite_int64()_ function shall overwite the contents of a BSON_TYPE_INT64 element in place.</p>
+    <p>This may only be done when the underlying bson document allows mutation.</p>
+    <p>It is a programming error to call this function when _iter_ is not obvserving an element of type BSON_TYPE_INT64.</p>
   </section>
 
 </page>
diff --git a/doc/bson_iter_recurse.page b/doc/bson_iter_recurse.page
@@ -28,11 +28,13 @@ bson_iter_recurse (const bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_recurse()_ function shall initialize _child_ using the embedded document or array currently observed by _iter_.</p>
+    <p>If there was a failure to initialize the _iter_, FALSE is returned and both _iter_ and _child_ should be considered invalid.</p>
+    <p>This should only be called when observing an element of type BSON_TYPE_ARRAY or BSON_TYPE_DOCUMENT.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>TRUE if _child_ has been intialized. Otherwise, both _child_ and _iter_ should be considered invalid.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_regex.page b/doc/bson_iter_regex.page
@@ -28,11 +28,12 @@ bson_iter_regex (const bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_regex()_ function shall retrieve the contents of a BSON_TYPE_REGEX element currently observed by _iter_.</p>
+    <p>It is invalid to call this function when not observing an element of type BSON_TYPE_REGEX.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A string containing the regex which should not be modified or freed. _options_ is set to the options provided for the regex.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_symbol.page b/doc/bson_iter_symbol.page
@@ -28,11 +28,13 @@ bson_iter_symbol (const bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The symbol element type is *deprecated* in the bson specification at http://bsonspec.org.</p>
+    <p>The _bson_iter_symbol()_ function shall return the contents of a BSON_TYPE_SYMBOL element.</p>
+    <p>if non-NULL, _length_ will be set to the length of the resulting string.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>The symbol and <code>length</code> is set.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_time_t.page b/doc/bson_iter_time_t.page
@@ -26,11 +26,11 @@ bson_iter_time_t (const bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_time_t()_ function shall return the number of seconds since the UNIX epoch, as contained in the BSON_TYPE_DATE_TIME element.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A <code>time_t</code> containing the number of seconds since the UNIX epoch.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_timestamp.page b/doc/bson_iter_timestamp.page
@@ -12,7 +12,11 @@
 
   <section id="synopsis">
     <title>Synopsis</title>
-    <synopsis><code mime="text/x-csrc"><![CDATA[void
+    <synopsis><code mime="text/x-csrc"><![CDATA[
+#define BSON_ITER_HOLDS_TIMESTAMP(iter) \
+   (bson_iter_type ((iter)) == BSON_TYPE_TIMESTAMP)
+
+void
 bson_iter_timestamp (const bson_iter_t *iter,
                      uint32_t          *timestamp,
                      uint32_t          *increment);
@@ -30,7 +34,9 @@ bson_iter_timestamp (const bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The BSON_TYPE_TIMESTAMP type is not a date/time and is typically used for intra-server communication.</p>
+    <p>You probably want <link xref="bson_iter_date_time">bson_iter_date_time()</link>.</p>
+    <p>The _bson_iter_timestamp()_ function shall return the contents of a BSON_TYPE_TIMESTAMP element. It is invalid to call this function while observing an element that is not of type BSON_TYPE_TIMESTAMP.</p>
   </section>
 
 </page>
diff --git a/doc/bson_iter_timeval.page b/doc/bson_iter_timeval.page
@@ -28,7 +28,7 @@ bson_iter_timeval (const bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_timeval()_ function shall return the number of seconds and microseconds since the UNIX epoch, as contained in the BSON_TYPE_DATE_TIME element into _tv_.</p>
   </section>
 
 </page>
diff --git a/doc/bson_iter_type.page b/doc/bson_iter_type.page
@@ -12,7 +12,32 @@
 
   <section id="synopsis">
     <title>Synopsis</title>
-    <synopsis><code mime="text/x-csrc"><![CDATA[bson_type_t
+    <synopsis><code mime="text/x-csrc"><![CDATA[typedef enum
+{
+   BSON_TYPE_EOD           = 0x00,
+   BSON_TYPE_DOUBLE        = 0x01,
+   BSON_TYPE_UTF8          = 0x02,
+   BSON_TYPE_DOCUMENT      = 0x03,
+   BSON_TYPE_ARRAY         = 0x04,
+   BSON_TYPE_BINARY        = 0x05,
+   BSON_TYPE_UNDEFINED     = 0x06,
+   BSON_TYPE_OID           = 0x07,
+   BSON_TYPE_BOOL          = 0x08,
+   BSON_TYPE_DATE_TIME     = 0x09,
+   BSON_TYPE_NULL          = 0x0A,
+   BSON_TYPE_REGEX         = 0x0B,
+   BSON_TYPE_DBPOINTER     = 0x0C,
+   BSON_TYPE_CODE          = 0x0D,
+   BSON_TYPE_SYMBOL        = 0x0E,
+   BSON_TYPE_CODEWSCOPE    = 0x0F,
+   BSON_TYPE_INT32         = 0x10,
+   BSON_TYPE_TIMESTAMP     = 0x11,
+   BSON_TYPE_INT64         = 0x12,
+   BSON_TYPE_MAXKEY        = 0x7F,
+   BSON_TYPE_MINKEY        = 0xFF,
+} bson_type_t;
+
+bson_type_t
 bson_iter_type (const bson_iter_t *iter);
 ]]></code></synopsis>
   </section>
@@ -26,11 +51,11 @@ bson_iter_type (const bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The <code>bson_iter_type()</code> function shall return the type of the ovserved element in a bson document.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A <code>bson_type_t</code>.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_utf8.page b/doc/bson_iter_utf8.page
@@ -12,7 +12,11 @@
 
   <section id="synopsis">
     <title>Synopsis</title>
-    <synopsis><code mime="text/x-csrc"><![CDATA[const char *
+    <synopsis><code mime="text/x-csrc"><![CDATA[
+#define BSON_ITER_HOLDS_UTF8(iter) \
+   (bson_iter_type ((iter)) == BSON_TYPE_UTF8)
+
+const char *
 bson_iter_utf8 (const bson_iter_t *iter,
                 uint32_t          *length);
 ]]></code></synopsis>
@@ -22,17 +26,20 @@ bson_iter_utf8 (const bson_iter_t *iter,
     <title>Parameters</title>
     <table>
       <tr><td><p>iter</p></td><td><p>A <link xref="bson_iter_t">bson_iter_t</link>.</p></td></tr>
-      <tr><td><p>length</p></td><td><p>A uint32_t.</p></td></tr>
+      <tr><td><p>length</p></td><td><p>An optional location for the length of the resulting UTF-8 encoded string.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>The _bson_iter_utf8()_ function shall retrieve the contents of a BSON_TYPE_UTF8 element currently observed by _iter_.</p>
+    <p>It is invalid to call this function while ovserving an element other than BSON_TYPE_UTF8.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A UTF-8 encoded string that has not been modified or freed.</p>
+    <p>It is suggested that the caller validate the content is valid UTF-8 before using this in other places. That can be done by calling _bson_utf8_validate()_ or validating the underlying _bson_t_ before iterating it.</p>
+    <p>Note that not all drivers use multi-byte representation for <code>\0</code> in UTF-8 encodings (commonly referred to as modified-UTF8). You probably want to take a look at the length field when marshaling to other runtimes.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_value.page b/doc/bson_iter_value.page
@@ -26,11 +26,11 @@ bson_iter_value (bson_iter_t *iter);
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Fetches the value for the currently observed type as a boxed type. This allows passing around the value without knowing the type at runtime.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A <link xref="bson_value_t">bson_value_t</link> that should not be modified or freed.</p>
   </section>
 </page>
diff --git a/doc/bson_iter_visit_all.page b/doc/bson_iter_visit_all.page
@@ -23,18 +23,18 @@ bson_iter_visit_all (bson_iter_t          *iter,
     <title>Parameters</title>
     <table>
       <tr><td><p>iter</p></td><td><p>A <link xref="bson_iter_t">bson_iter_t</link>.</p></td></tr>
-      <tr><td><p>visitor</p></td><td><p>A bson_visitor_t.</p></td></tr>
-      <tr><td><p>data</p></td><td><p>A (null).</p></td></tr>
+      <tr><td><p>visitor</p></td><td><p>A <link xref="bson_visitor_t">bson_visitor_t</link>.</p></td></tr>
+      <tr><td><p>data</p></td><td><p>Optional data for <code>visitor</code>.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>A convenience function to iterate all remaining fields of <code>iter</code> using the callback vtable provided by <code>visitor</code>.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>true if visitation was pre-maturely stopped by a callback function. Otherwise false.</p>
   </section>
 </page>