doc: more string docs.

mwhittaker · May 29, 2014 · 086cde9 · 086cde9
1 parent db6500b
commit 086cde9
Show file tree

Hide file tree

Showing 10 changed files with 28 additions and 24 deletions.
diff --git a/doc/bson_iter_dup_utf8.page b/doc/bson_iter_dup_utf8.page
@@ -28,7 +28,7 @@ bson_iter_dup_utf8 (const bson_iter_t *iter,
 
   <section id="description">
     <title>Description</title>
-    <p>This function is similar to <link xref="bson_iter_utf8">bson_iter_utf8()</link> except that it calls <link xref="bson_strdup">bson_strdup()</link> on the result.</p>
+    <p>This function is similar to <link xref="bson_iter_utf8">bson_iter_utf8()</link> except that it calls <link xref="bson_strndup">bson_strndup()</link> on the result.</p>
   </section>
 
   <section id="return">

diff --git a/doc/bson_snprintf.page b/doc/bson_snprintf.page
@@ -23,19 +23,20 @@ bson_snprintf (char       *str,
   <section id="parameters">
     <title>Parameters</title>
     <table>
-      <tr><td><p><code>str</code></p></td><td><p>A UNKNOWN.</p></td></tr>
-      <tr><td><p><code>size</code></p></td><td><p>A size_t.</p></td></tr>
-      <tr><td><p><code>format</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>str</code></p></td><td><p>The destination buffer.</p></td></tr>
+      <tr><td><p><code>size</code></p></td><td><p>The size of <code>str</code>.</p></td></tr>
+      <tr><td><p><code>format</code></p></td><td><p>A printf style format string.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>This is a portable wrapper around <code>snprintf()</code>. It also enforces a trailing <code>\0</code> in the resulting string.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>The number of bytes written to <code>str</code>.</p>
   </section>
+
 </page>
diff --git a/doc/bson_strdup.page b/doc/bson_strdup.page
@@ -20,17 +20,18 @@ bson_strdup (const char *str);
   <section id="parameters">
     <title>Parameters</title>
     <table>
-      <tr><td><p><code>str</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>str</code></p></td><td><p>A string.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Copies <code>str</code> into a new string. If <code>str</code> is NULL, then NULL is returned.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A newly allocated string that should be freed with bson_free().</p>
   </section>
+
 </page>
diff --git a/doc/bson_strdup_printf.page b/doc/bson_strdup_printf.page
@@ -21,17 +21,18 @@ bson_strdup_printf (const char *format,
   <section id="parameters">
     <title>Parameters</title>
     <table>
-      <tr><td><p><code>format</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>format</code></p></td><td><p>A printf style format string.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>This function performs a printf style format but into a newly allocated string.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A newly allocated string that should be freed with bson_free().</p>
   </section>
+
 </page>
diff --git a/doc/bson_strdupv_printf.page b/doc/bson_strdupv_printf.page
@@ -21,18 +21,19 @@ bson_strdupv_printf (const char *format,
   <section id="parameters">
     <title>Parameters</title>
     <table>
-      <tr><td><p><code>format</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>format</code></p></td><td><p>A printf style format string.</p></td></tr>
       <tr><td><p><code>args</code></p></td><td><p>A va_list.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>This function is like <link xref="bson_strdup_printf">bson_strdup_printf()</link> except takes a va_list of parameters.</p>
   </section>
 
   <section id="return">
     <title>Returns</title>
-    <p>TODO:</p>
+    <p>A newly allocated string that should be freed with bson_free().</p>
   </section>
+
 </page>
diff --git a/doc/bson_strfreev.page b/doc/bson_strfreev.page
@@ -20,13 +20,13 @@ bson_strfreev (char **strv);
   <section id="parameters">
     <title>Parameters</title>
     <table>
-      <tr><td><p><code>strv</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>strv</code></p></td><td><p>A NULL-terminated array of strings to free, including the array.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>This will free each string in a NULL-terminated array of strings and then the array itself.</p>
   </section>
 
 </page>
diff --git a/doc/bson_string_append.page b/doc/bson_string_append.page
@@ -22,13 +22,13 @@ bson_string_append (bson_string_t *string,
     <title>Parameters</title>
     <table>
       <tr><td><p><code>string</code></p></td><td><p>A <link xref="bson_string_t">bson_string_t</link>.</p></td></tr>
-      <tr><td><p><code>str</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>str</code></p></td><td><p>A string.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Appends the ASCII or UTF-8 encoded string <code>str</code> to <code>string</code>. This is not suitable for embedding NULL's in strings.</p>
   </section>
 
 </page>
diff --git a/doc/bson_string_append_c.page b/doc/bson_string_append_c.page
@@ -22,13 +22,13 @@ bson_string_append_c (bson_string_t *string,
     <title>Parameters</title>
     <table>
       <tr><td><p><code>string</code></p></td><td><p>A <link xref="bson_string_t">bson_string_t</link>.</p></td></tr>
-      <tr><td><p><code>str</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>str</code></p></td><td><p>An ASCII char.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Appends <code>c</code> to the string builder <code>string</code>.</p>
   </section>
 
 </page>
diff --git a/doc/bson_string_append_printf.page b/doc/bson_string_append_printf.page
@@ -23,13 +23,13 @@ bson_string_append_printf (bson_string_t *string,
     <title>Parameters</title>
     <table>
       <tr><td><p><code>string</code></p></td><td><p>A <link xref="bson_string_t">bson_string_t</link>.</p></td></tr>
-      <tr><td><p><code>format</code></p></td><td><p>A UNKNOWN.</p></td></tr>
+      <tr><td><p><code>format</code></p></td><td><p>A printf style format string.</p></td></tr>
     </table>
   </section>
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Like bson_string_append() but formats a printf style string and then appends that to <code>string</code>.</p>
   </section>
 
 </page>
diff --git a/doc/bson_string_append_unichar.page b/doc/bson_string_append_unichar.page
@@ -28,7 +28,7 @@ bson_string_append_unichar (bson_string_t *string,
 
   <section id="description">
     <title>Description</title>
-    <p>TODO:</p>
+    <p>Appends a unicode character to string. The character will be encoded into it's multi-byte UTF-8 representation.</p>
   </section>
 
 </page>