cursor and gridfs documentation

also:
* changes to the gridfs api to make it complete

Author: hanumantmk

.gitignore

@@ -29,6 +29,8 @@ mongoc-tail
 *.pc
 stamp-h1
 *.swp
+example-client
+example-gridfs
 repltest1
 shardtest1
 shardtest2

doc/Makefile.include

@@ -1,10 +1,14 @@
-MAN3 = $(MONGOC_SYMBOLS)
+MAN3 = $(top_srcdir)/doc/todo.3 $(MONGOC_SYMBOLS)
 
 MAN7 = \
 	$(top_srcdir)/doc/mongoc_client.7 \
 	$(top_srcdir)/doc/mongoc_client_pool.7 \
 	$(top_srcdir)/doc/mongoc_collection.7 \
+	$(top_srcdir)/doc/mongoc_cursor.7 \
 	$(top_srcdir)/doc/mongoc_database.7 \
+	$(top_srcdir)/doc/mongoc_gridfs.7 \
+	$(top_srcdir)/doc/mongoc_gridfs_file.7 \
+	$(top_srcdir)/doc/mongoc_gridfs_file_list.7 \
 	$(top_srcdir)/doc/mongoc_uri.7
 
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
@@ -35,14 +39,30 @@ SUFFIXES=.html .txt .xml .3 .7
 EXAMPLE_DIR = $(abs_top_srcdir)/examples
 
 .txt.html:
-	asciidoc -d manpage -b xhtml11 -f $(top_srcdir)/doc/asciidoc.conf \
-           -aexamples=$(EXAMPLE_DIR) -amongoc_version=@PACKAGE_VERSION@ -o$@ $<
+	if [ -L $< ]; then \
+	   ln -fs `basename \`readlink $<\` .txt`.html $@; \
+	else \
+	   asciidoc -d manpage -b xhtml11 -f $(top_srcdir)/doc/asciidoc.conf \
+	      -aexamples=$(EXAMPLE_DIR) -amongoc_version=@PACKAGE_VERSION@ -o$@ $<; \
+	fi
 .txt.xml:
-	asciidoc -d manpage -b docbook -f $(top_srcdir)/doc/asciidoc.conf \
-           -aexamples=$(EXAMPLE_DIR) -amongoc_version=@PACKAGE_VERSION@ \
-           -amongoc_manname=$(*F) -o$@ $<
+	if [ -L $< ]; then \
+	   ln -fs `basename \`readlink $<\` .txt`.xml $@; \
+	else \
+	   asciidoc -d manpage -b docbook -f $(top_srcdir)/doc/asciidoc.conf \
+	      -aexamples=$(EXAMPLE_DIR) -amongoc_version=@PACKAGE_VERSION@ \
+	      -amongoc_manname=$(*F) -o$@ $<; \
+	fi
 .xml.3:
-	xmlto man -o $(top_srcdir)/doc $<
+	if [ -L $< ]; then \
+	   ln -fs `basename \`readlink $<\` .xml`.3 $@; \
+        else \
+	   xmlto man -o $(top_srcdir)/doc $<; \
+	fi
 .xml.7:
-	xmlto man -o $(top_srcdir)/doc $<
+	if [ -L $< ]; then \
+	   ln -fs `basename \`readlink $<\` .xml`.3 $@; \
+        else \
+	   xmlto man -o $(top_srcdir)/doc $<; \
+        fi
 endif

doc/mongoc_cursor.txt

@@ -0,0 +1,101 @@
+mongoc_cursor(7)
+================
+
+
+NAME
+----
+mongoc_cursor - MongoDB cursor connection abstraction
+
+
+SYNOPSIS
+--------
+
+[source, c]
+---------------
+const bson_t *doc;
+mongoc_cursor_t * cursor;
+
+cursor = mongoc_collection_find (collection,
+                                 MONGOC_QUERY_NONE,
+                                 0,
+                                 0,
+                                 &query,
+                                 NULL,  /* Fields, NULL for all. */
+                                 NULL); /* Read Prefs, NULL for default */
+
+while (mongoc_cursor_next (cursor, &doc)) {
+   do_something(doc);
+}
+---------------
+
+
+DESCRIPTION
+-----------
+_mongoc_cursor_ provides access to a MongoDB query cursor.  It wraps up the
+wire protocol negotation required to initiate a query and retreive an unknown
+number of documents.
+
+Cursors are lazy, meaning that no network traffic occurs until the first
+linkmongoc:mongoc_cursor_next[3].
+
+At that point we can:
+
+* Determine which host we've connected to with
+  linkmongoc:mongoc_cursor_get_host[3].
+* Retreive more records with repeated calls to linkmongoc:mongoc_cursor_next[3]
+* Test for more records with linkmongoc:mongoc_cursor_more[3]
+* Clone a query to repeat execution at a later point with
+  linkmongoc:mongoc_cursor_clone[3]
+* Test for errors with linkmongoc:mongoc_cursor_error[3]
+
+
+THREAD SAFETY
+-------------
+
+_mongoc_cursor_ is *NOT* thread-safe and should only be used from one thread at
+a time. 
+
+LIFECYCLE
+---------
+
+The bson objects set in linkmongoc:mongoc_cursor_next[3] are ephemeral and good
+until the next call.  linkmongoc:mongoc_cursor_destroy[3] must be called to
+clean up, even in the case of exhausted cursors.
+
+EXAMPLE
+-------
+
+The following example connects to a single MongoDB instance and performs a
+simple query against it. The resulting documents are printed as 'JSON' to
+standard output.
+
+[source,c]
+---------------
+include::{examples}/example-client.c[]
+---------------
+
+
+SEE ALSO
+--------
+
+FUNCTIONS
+~~~~~~~~~
+
+linkmongoc:mongoc_cursor_clone[3]
+linkmongoc:mongoc_cursor_destroy[3]
+linkmongoc:mongoc_cursor_error[3]
+linkmongoc:mongoc_cursor_get_host[3]
+linkmongoc:mongoc_cursor_more[3]
+linkmongoc:mongoc_cursor_next[3]
+
+RELATED
+~~~~~~~
+
+linkmongoc:mongoc_client[7]
+linkmongoc:mongoc_collection[7]
+
+
+AUTHORS
+-------
+
+This page was written by MongoDB Inc.

doc/mongoc_cursor_clone.txt

@@ -0,0 +1,45 @@
+mongoc_cursor_clone(3)
+======================
+
+
+NAME
+----
+mongoc_cursor_clone - clone a mongoc cursor
+
+
+SYNOPSIS
+--------
+[source,c]
+-----------------------
+mongoc_cursor_t *
+mongoc_cursor_clone (const mongoc_cursor_t *cursor);
+-----------------------
+
+
+DESCRIPTION
+-----------
+The _mongoc_cursor_clone()_ function shall create a copy of a
+linkmongoc:mongoc_cursor[7].
+
+Clone copies all of the set up behind a cursor.  I.e. the query, fields, flags,
+etc.  It does not copy any run time state.
+
+
+RETURN VALUE
+------------
+The _mongoc_cursor_clone()_ function returns a new linkmongoc:mongoc_cursor[7].
+
+ERRORS
+------
+No errors are defined.
+
+
+SEE ALSO
+--------
+linkmongoc:mongoc_cursor[7]
+
+
+AUTHORS
+-------
+
+This page was written by MongoDB Inc.

doc/mongoc_cursor_clone.txt

@@ -0,0 +1,41 @@
+mongoc_cursor_destroy(3)
+========================
+
+
+NAME
+----
+mongoc_cursor_destroy - destroy a mongoc cursor
+
+
+SYNOPSIS
+--------
+[source,c]
+-----------------------
+void
+mongoc_cursor_destroy (mongoc_cursor_t *cursor);
+-----------------------
+
+
+DESCRIPTION
+-----------
+The _mongoc_cursor_destroy()_ function shall destroy the cursor referenced by
+the 'cursor' argument and any resources associated with the cursor.
+
+RETURN VALUE
+------------
+The _mongoc_cursor_destroy()_ function has no return value.
+
+ERRORS
+------
+No errors are defined.
+
+
+SEE ALSO
+--------
+linkmongoc:mongoc_cursor[7]
+
+
+AUTHORS
+-------
+
+This page was written by MongoDB Inc.

doc/mongoc_cursor_destroy.txt

@@ -0,0 +1,43 @@
+mongoc_cursor_error(3)
+======================
+
+
+NAME
+----
+mongoc_cursor_error - get errors on a mongoc cursor
+
+
+SYNOPSIS
+--------
+[source,c]
+-----------------------
+bson_bool_t
+mongoc_cursor_error (mongoc_cursor_t *cursor,
+                     bson_error_t    *error);
+-----------------------
+
+
+DESCRIPTION
+-----------
+The _mongoc_cursor_error()_ function shall set 'error' with the value of the
+last error on the 'cursor'.
+
+RETURN VALUE
+------------
+The _mongoc_cursor_error()_ function returns true if there is an error on the
+cursor.  In the absence of an error, it returns false.
+
+ERRORS
+------
+No errors are defined.
+
+
+SEE ALSO
+--------
+linkmongoc:mongoc_cursor[7]
+
+
+AUTHORS
+-------
+
+This page was written by MongoDB Inc.