1 files changed, 62 insertions, 0 deletions
diff --git a/docs/tutorial/tut_bson_build.h b/docs/tutorial/tut_bson_build.h
new file mode 100644
index 0000000..5c5eb54
--- /dev/null
+++ b/docs/tutorial/tut_bson_build.h
@@ -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 }
+ */