Permalink
Browse files

docs: Beginnings of a tutorial.

Factored the API doc links out of src/mongo.h, and moved them into
docs/api.h instead.

Furthermore, started writing a Tutorial: for now, it covers BSON
building, but the infrastructure is ready for more.
  • Loading branch information...
1 parent 84bb8cf commit 3fb1dd44dcb9388469956c298e89ed61baaa0399 @algernon committed Jun 5, 2011
View
@@ -16,6 +16,6 @@ ltmain.sh
m4/
missing
tests/*.ok
-docs/
+docs/html/
b/
.pc/
View
@@ -65,11 +65,11 @@ WARN_NO_PARAMDOC = YES
# configuration options related to the input files
#---------------------------------------------------------------------------
-INPUT = @top_srcdir@/src/
+INPUT = @top_srcdir@/src/ @top_srcdir@/docs/ @top_srcdir@/docs/tutorial/
INPUT_ENCODING = UTF-8
-EXAMPLE_PATH = @top_srcdir@/examples/
-EXAMPLE_PATTERNS = *.c
+EXAMPLE_PATH = @top_srcdir@/docs/tutorial/examples/
+EXAMPLE_PATTERNS = *.c *.json
#---------------------------------------------------------------------------
# configuration options related to source browsing
View
@@ -1,4 +1,4 @@
-SUBDIRS = src tests examples
+SUBDIRS = docs src tests examples
ACLOCAL_AMFLAGS = -I m4 --install
EXTRA_DIST = NEWS README.rst
View
@@ -152,6 +152,8 @@ AC_SUBST(openssl_pc)
AC_OUTPUT(
Doxyfile
Makefile
+ docs/Makefile
+ docs/tutorial/Makefile
examples/Makefile
src/Makefile
src/libmongo-client.pc
View
@@ -0,0 +1,3 @@
+SUBDIRS = tutorial
+
+EXTRA_DIST = api.h
View
@@ -0,0 +1,40 @@
+/** @page api API Documentation
+ *
+ * On these pages, one will find the complete API documentation.
+ *
+ * @section Structure
+ *
+ * The library can be split into four major parts:
+ * - bson: The low-level BSON implementation. @see bson_mod
+ * - mongo-wire: Functions to construct packets that can be sent
+ * later. @see mongo_wire
+ * - mongo-client: The high-level API that deals with the
+ * network. @see mongo_client
+ * - mongo-utils: Various miscellaneous utilities related to either
+ * BSON or MongoDB. @see mongo_util
+ * - mongo-sync: Wrappers around the wire commands, that talk to the
+ * network aswell, in a synchronous, blocking manner. @see
+ * mongo_sync.
+ * - mongo-sync-cursor: Cursor API on top of the synchronous
+ * API. @see mongo_sync_cursor.
+ * - mongo-sync-pool: Simple connection pooling on top of
+ * mongo-sync, @see mongo_sync_pool_api.
+ *
+ * The intended way to use the library to work with MongoDB is to
+ * first construct the BSON objects, then construct the packets, and
+ * finally send the packets out to the network.
+ *
+ * The reason behind the split between packet construction and sending
+ * is because we want to be able to construct packets in one thread
+ * and send it in another, if so need be.
+ *
+ * This split also allows scenarios where the packet must be sent over
+ * a medium the library was not prepared for (such as an SSL tunnel),
+ * or when the packet is supposed to be sent to multiple destinations
+ * (for whatever reason - perhaps for being logged to a file for
+ * debugging purposes).
+ *
+ * All in all, this separation between modules provides a great deal
+ * of flexibility.
+
+ */
@@ -0,0 +1,2 @@
+EXTRA_DIST = tutorial.h \
+ tut_bson.h tut_bson_build.h examples/tut_bson_build.c examples/tut_bson_build.json
@@ -0,0 +1,81 @@
+#include <mongo.h>
+
+#include <string.h>
+#include <stdio.h>
+
+int
+main (void)
+{
+ bson *b_new, *b_builder, b_builder_full;
+ bson *page1, *page2, *pages;
+
+ page1 = bson_new ();
+ bson_append_string (page1, "title", "BSON tutorial", -1);
+ bson_append_string (page1, "content", "...", -1);
+ bson_append_int32 (page1, "importance", 1);
+ bson_finish (page1);
+
+ page2 = bson_new ();
+ bson_append_string (page2, "title", "Some other thing", -1);
+ bson_append_string (page2, "content", "...", -1);
+ bson_append_int32 (page2, "importance", 0);
+ bson_finish (page2);
+
+ pages = bson_new ();
+ bson_append_document (pages, "1", page1);
+ bson_append_document (pages, "2", page2);
+ bson_finish (pages);
+
+ b_new = bson_new ();
+ bson_append_string (b_new, "author", "Gergely Nagy", -1);
+ bson_append_array (b_new, "pages", pages);
+ bson_append_boolean (b_new, "inline", TRUE);
+ bson_finish (b_new);
+
+ b_builder = bson_build (BSON_TYPE_STRING, "author", "Gergely Nagy", -1,
+ BSON_TYPE_ARRAY, "pages", pages,
+ BSON_TYPE_BOOLEAN, "inline", TRUE,
+ BSON_TYPE_NONE);
+ bson_finish (b_builder);
+
+ b_builder_full = bson_build_full
+ (BSON_TYPE_STRING, "author", FALSE, "Gergely Nagy", -1,
+ BSON_TYPE_ARRAY, "pages", TRUE,
+ bson_build_full (BSON_TYPE_DOCUMENT, "1", TRUE,
+ bson_build (BSON_TYPE_STRING, "title", "BSON tutorial", -1,
+ BSON_TYPE_STRING, "content", "...", -1,
+ BSON_TYPE_INT32, "importance", 1,
+ BSON_TYPE_NONE),
+ BSON_TYPE_DOCUMENT, "2", TRUE,
+ bson_build (BSON_TYPE_STRING, "title", "Some other thing", -1,
+ BSON_TYPE_STRING, "content", "...", -1,
+ BSON_TYPE_INT32, "importance", 0,
+ BSON_TYPE_NONE),
+ BSON_TYPE_NONE),
+ BSON_TYPE_BOOLEAN, "inline", FALSE, TRUE,
+ BSON_TYPE_NONE);
+ bson_finish (b_builder_full);
+
+ if (bson_size (b_new) != bson_size (b_builder) ||
+ bson_size (b_new) != bson_size (b_builder_full))
+ {
+ fprintf (stderr, "There's something fishy: the three BSON objects have different sizes");
+ return 1;
+ }
+
+ if (memcmp (bson_data (b_new), bson_data (b_builder), bson_size (b_new)) != 0 ||
+ memcmp (bson_data (b_new), bson_data (b_builder_full), bson_size (b_new)) != 0)
+ {
+ fprintf (stderr, "The BSON objects do not match. Something smells.");
+ return 1;
+ }
+
+ bson_free (b_builder_full);
+ bson_free (b_builder);
+ bson_free (b_new);
+ bson_free (pages);
+ bson_free (page2);
+ bson_free (page1);
+
+ return 0;
+}
@@ -0,0 +1,16 @@
+{
+ author: "Gergely Nagy",
+ pages: [
+ {
+ title: "BSON tutorial",
+ content: "...",
+ importance: 1
+ },
+ {
+ title: "Some other thing",
+ content: "...",
+ importance: 0
+ }
+ ],
+ inline: true
+}
View
@@ -0,0 +1,9 @@
+/** @page tut_bson Working with BSON objects
+ *
+ * In this section, we'll cover the basics of working with BSON
+ * objects in a few big steps. Working with BSON is fairly
+ * straightforward, so we will not be going into much details here.
+ *
+ * Contents:
+ * - @subpage tut_bson_build
+ */
@@ -0,0 +1,62 @@
+/** @page tut_bson_build Building BSON objects
+ *
+ * Our first task will be to build a BSON document, which we can later
+ * insert into MongoDB. For this example, we want something more
+ * complex than a simple "Hello World"-style object, so we can
+ * showcase all the interesting functions of the BSON API.
+ *
+ * Lets build a document that would look like this, if we were writing
+ * JSON:
+ * @verbinclude tut_bson_build.json
+ *
+ * @dontinclude tut_bson_build.c
+ *
+ * First we start by including the main libmongo-client header. It's
+ * convenient to include the whole lot instead of including the used
+ * headers one by one, unless one's embedding only parts of the
+ * library.
+ * @until mongo.h
+ *
+ * @until {
+ *
+ * We'll be building the same BSON object in various different ways,
+ * so we declare a few more variables than we'd normally need.
+ * @until pages
+ *
+ * Next, we create the two pages:
+ * @until bson_finish (page2)
+ *
+ * Then we construct the "pages" array. Do note how we set the key to
+ * "1" and "2", and how pages is just a document! This is because in
+ * BSON, an array is a document that has a special type, and where
+ * keys are numbers.
+ * @until bson_finish (pages)
+ *
+ * Finally, now that we have all the subdocuments ready, we build up
+ * our main object:
+ * @until bson_finish (b_new)
+ *
+ * And that's about it! But surely, there is an easier way to do
+ * this... And indeed, there is, using bson_build():
+ * @until bson_finish (b_builder)
+ *
+ * Much cleaner, but still, we had to create the pages array in three
+ * steps beforehand. Couldn't we do it in one gigantic function call
+ * instead?
+ * @until bson_finish (b_builder_full)
+ *
+ * Wonderful! We have three BSON objects created now, in three
+ * different ways! But are they the same? That's really easy to figure
+ * out. As a quick check, we can compare their sizes: if they do not
+ * match, we can bail out fast:
+ * @until }
+ *
+ * Or, we can do a more expensive comparsion, and compare the data:
+ * @until }
+ *
+ * And now that we are done, we free up the resources we allocated.
+ * @until bson_free (page1)
+ *
+ *
+ * @until }
+ */
View
@@ -0,0 +1,13 @@
+/** @page tutorial Tutorial
+ *
+ * These pages will attempt to guide one through the libmongo-client
+ * library, starting from the basic BSON building blocks, through the
+ * low level wire protocol API, until the highest level synchronous
+ * API.
+ *
+ * The documentation assumes a reasonable amount of C knowledge, and
+ * basic familiarity with MongoDB concepts.
+ *
+ * Contents:
+ * - @subpage tut_bson
+ */
View
@@ -36,40 +36,7 @@
* libmongo-client is an alternative MongoDB driver for the C
* language, with clarity, correctness and completeness in mind.
*
- * On these pages, one will find the complete API documentation.
- *
- * @section Structure
- *
- * The library can be split into four major parts:
- * - bson: The low-level BSON implementation. @see bson_mod
- * - mongo-wire: Functions to construct packets that can be sent
- * later. @see mongo_wire
- * - mongo-client: The high-level API that deals with the
- * network. @see mongo_client
- * - mongo-utils: Various miscellaneous utilities related to either
- * BSON or MongoDB. @see mongo_util
- * - mongo-sync: Wrappers around the wire commands, that talk to the
- * network aswell, in a synchronous, blocking manner. @see
- * mongo_sync.
- * - mongo-sync-cursor: Cursor API on top of the synchronous
- * API. @see mongo_sync_cursor.
- * - mongo-sync-pool: Simple connection pooling on top of
- * mongo-sync, @see mongo_sync_pool_api.
- *
- * The intended way to use the library to work with MongoDB is to
- * first construct the BSON objects, then construct the packets, and
- * finally send the packets out to the network.
- *
- * The reason behind the split between packet construction and sending
- * is because we want to be able to construct packets in one thread
- * and send it in another, if so need be.
- *
- * This split also allows scenarios where the packet must be sent over
- * a medium the library was not prepared for (such as an SSL tunnel),
- * or when the packet is supposed to be sent to multiple destinations
- * (for whatever reason - perhaps for being logged to a file for
- * debugging purposes).
- *
- * All in all, this separation between modules provides a great deal
- * of flexibility.
+ * Contents:
+ * - @subpage api
+ * - @subpage tutorial
*/

0 comments on commit 3fb1dd4

Please sign in to comment.