Skip to content

Commit b6898f0

Browse files
hanumantmkhanumantmk
committed
Beginning of documenting everything
a bunch of docs aren't done, symlinked to a todo.txt to make the build happy
1 parent d4c1abc commit b6898f0

File tree

160 files changed

+3031
-78
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

160 files changed

+3031
-78
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ mongoc-tail
2727
*.pc
2828
stamp-h1
2929
*.swp
30+
example-client
3031
repltest1
3132
shardtest1
3233
shardtest2

‎Makefile.am

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ include mongoc/Makefile.include
55
include examples/Makefile.include
66
include tests/Makefile.include
77
include tools/Makefile.include
8+
include doc/Makefile.include
89

910
if HAVE_PYTHON
1011
include bindings/python/Makefile.include

‎acinclude.m4

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
dnl ##############################################################################
2+
dnl # MONGOC_CHECK_DOC_BUILD #
3+
dnl # Check whether to build documentation and install man-pages #
4+
dnl ##############################################################################
5+
AC_DEFUN([MONGOC_CHECK_DOC_BUILD], [{
6+
# Allow user to disable doc build
7+
AC_ARG_WITH([documentation], [AS_HELP_STRING([--without-documentation],
8+
[disable documentation build even if asciidoc and xmlto are present [default=no]])])
9+
10+
if test "x$with_documentation" = "xno"; then
11+
mongoc_build_doc="no"
12+
mongoc_install_man="no"
13+
else
14+
# Determine whether or not documentation should be built and installed.
15+
mongoc_build_doc="yes"
16+
mongoc_install_man="yes"
17+
# Check for asciidoc and xmlto and don't build the docs if these are not installed.
18+
AC_CHECK_PROG(mongoc_have_asciidoc, asciidoc, yes, no)
19+
AC_CHECK_PROG(mongoc_have_xmlto, xmlto, yes, no)
20+
if test "x$mongoc_have_asciidoc" = "xno" -o "x$mongoc_have_xmlto" = "xno"; then
21+
mongoc_build_doc="no"
22+
# Tarballs built with 'make dist' ship with prebuilt documentation.
23+
if ! test -f doc/mongoc.7; then
24+
mongoc_install_man="no"
25+
AC_MSG_WARN([You are building an unreleased version of Mongoc and asciidoc or xmlto are not installed.])
26+
AC_MSG_WARN([Documentation will not be built and manual pages will not be installed.])
27+
fi
28+
fi
29+
30+
# Do not install man pages if on mingw
31+
if test "x$mongoc_on_mingw32" = "xyes"; then
32+
mongoc_install_man="no"
33+
fi
34+
fi
35+
36+
AC_MSG_CHECKING([whether to build documentation])
37+
AC_MSG_RESULT([$mongoc_build_doc])
38+
39+
AC_MSG_CHECKING([whether to install manpages])
40+
AC_MSG_RESULT([$mongoc_install_man])
41+
42+
AM_CONDITIONAL(BUILD_DOC, test "x$mongoc_build_doc" = "xyes")
43+
AM_CONDITIONAL(INSTALL_MAN, test "x$mongoc_install_man" = "xyes")
44+
}])

‎configure.ac

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,23 @@ fi
173173
AC_SUBST([MONGOC_ENABLE_SSL])
174174

175175

176+
dnl **************************************************************************
177+
dnl Optionally check for Asciidoc and xmlto for documentation
178+
dnl **************************************************************************
179+
AC_ARG_VAR([XMLTO], [Path to xmlto command])
180+
AC_PATH_PROG([XMLTO], [xmlto])
181+
AC_ARG_VAR([ASCIIDOC], [Path to asciidoc command])
182+
AC_PATH_PROG([ASCIIDOC], [asciidoc])
183+
184+
MONGOC_CHECK_DOC_BUILD
185+
186+
187+
dnl **************************************************************************
188+
dnl Create (3) doc targets for each public symbol
189+
dnl **************************************************************************
190+
MONGOC_SYMBOLS=`sed -e 's/.*/$(top_srcdir)\/doc\/&.3/' < mongoc/libmongoc.symbols | xargs`
191+
AC_SUBST([MONGOC_SYMBOLS])
192+
176193
dnl **************************************************************************
177194
dnl Check for necessary libraries.
178195
dnl **************************************************************************

‎doc/.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.3
2+
*.7
3+
*.html

‎doc/Makefile.include

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
MAN3 = $(MONGOC_SYMBOLS)
2+
3+
MAN7 = \
4+
$(top_srcdir)/doc/mongoc_client.7 \
5+
$(top_srcdir)/doc/mongoc_client_pool.7 \
6+
$(top_srcdir)/doc/mongoc_collection.7 \
7+
$(top_srcdir)/doc/mongoc_database.7 \
8+
$(top_srcdir)/doc/mongoc_uri.7
9+
10+
MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
11+
12+
MAN_TXT = \
13+
$(MAN3:%.3=%.txt) \
14+
$(MAN7:%.7=%.txt)
15+
16+
MAN_HTML = $(MAN_TXT:%.txt=%.html)
17+
18+
if INSTALL_MAN
19+
dist_man_MANS = $(MAN_DOC)
20+
endif
21+
22+
EXTRA_DIST += $(top_srcdir)/doc/asciidoc.conf $(MAN_TXT)
23+
if BUILD_DOC
24+
EXTRA_DIST += $(MAN_HTML)
25+
endif
26+
27+
MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML)
28+
29+
doc : $(top_srcdir)/doc/asciidoc.conf $(DOC_EXAMPLES) $(MAN_DOC) $(MAN_HTML)
30+
dist-hook : doc
31+
32+
if BUILD_DOC
33+
SUFFIXES=.html .txt .xml .3 .7
34+
35+
EXAMPLE_DIR = $(abs_top_srcdir)/examples
36+
37+
.txt.html:
38+
asciidoc -d manpage -b xhtml11 -f $(top_srcdir)/doc/asciidoc.conf \
39+
-aexamples=$(EXAMPLE_DIR) -amongoc_version=@PACKAGE_VERSION@ -o$@ $<
40+
.txt.xml:
41+
asciidoc -d manpage -b docbook -f $(top_srcdir)/doc/asciidoc.conf \
42+
-aexamples=$(EXAMPLE_DIR) -amongoc_version=@PACKAGE_VERSION@ \
43+
-amongoc_manname=$(*F) -o$@ $<
44+
.xml.3:
45+
xmlto man -o $(top_srcdir)/doc $<
46+
.xml.7:
47+
xmlto man -o $(top_srcdir)/doc $<
48+
endif

‎doc/asciidoc.conf

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
[paradef-default]
2+
literal-style=template="literalparagraph"
3+
4+
[macros]
5+
(?su)[\\]?(?P<name>linkmongoc):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
6+
7+
ifdef::backend-docbook[]
8+
[linkmongoc-inlinemacro]
9+
{0%{target}}
10+
{0#<citerefentry>}
11+
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
12+
{0#</citerefentry>}
13+
endif::backend-docbook[]
14+
15+
ifdef::backend-xhtml11[]
16+
[linkmongoc-inlinemacro]
17+
<a href="{target}.html">{target}{0?({0})}</a>
18+
endif::backend-xhtml11[]
19+
20+
ifdef::doctype-manpage[]
21+
ifdef::backend-docbook[]
22+
[header]
23+
template::[header-declarations]
24+
<refentry>
25+
<refmeta>
26+
<refentrytitle>{mantitle}</refentrytitle>
27+
<manvolnum>{manvolnum}</manvolnum>
28+
<refmiscinfo class="source">Mongoc</refmiscinfo>
29+
<refmiscinfo class="version">{mongoc_version}</refmiscinfo>
30+
<refmiscinfo class="manual">Mongoc Manual</refmiscinfo>
31+
</refmeta>
32+
<refnamediv>
33+
<refname>{mongoc_manname}</refname>
34+
<refpurpose>{manpurpose}</refpurpose>
35+
</refnamediv>
36+
endif::backend-docbook[]
37+
endif::doctype-manpage[]
38+
39+
ifdef::backend-xhtml11[]
40+
[footer]
41+
</div>
42+
{disable-javascript%<div id="footnotes"><hr /></div>}
43+
<div id="footer">
44+
<div id="footer-text">
45+
Mongoc {mongoc_version}<br />
46+
Last updated {docdate} {doctime}
47+
</div>
48+
</div>
49+
</body>
50+
</html>
51+
endif::backend-xhtml11[]

‎doc/mongoc_client.txt

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
mongoc_client(7)
2+
================
3+
4+
5+
NAME
6+
----
7+
mongoc_client - MongoDB client connection abstraction
8+
9+
10+
SYNOPSIS
11+
--------
12+
13+
[source, c]
14+
---------------
15+
#include <mongoc.h>
16+
17+
mongoc_client_t * client;
18+
19+
client = mongoc_client_new(uri_string);
20+
---------------
21+
22+
23+
DESCRIPTION
24+
-----------
25+
_mongoc_client_ provides access to a MongoDB node, replica-set, or
26+
sharded-cluster. It maintains management of underlying sockets and routing to
27+
individual nodes based on linkmongoc:mongoc_read_prefs[7] or
28+
linkmongoc:mongoc_write_concern[7]
29+
30+
31+
STREAMS
32+
-------
33+
The underlying transport for a given client can be customized, wrapped or
34+
replaced by any implementation that fulfills linkmongoc:mongoc_stream[7]. A
35+
custom transport can be set with
36+
linkmongoc:mongoc_client_set_stream_initiator[3].
37+
38+
39+
THREAD SAFETY
40+
-------------
41+
42+
_mongoc_client_ is *NOT* thread-safe and should only be used from one thread at
43+
a time. When used in multi-threaded scenarios, it is recommended that you use
44+
linkmongoc:mongoc_client_pool[7] to retrieve a _mongoc_client_ for your thread.
45+
46+
LIFECYCLE
47+
---------
48+
49+
It is an error to call linkmongoc:mongoc_client_destroy[3] on a client that has
50+
operations pending. It is required that you release
51+
linkmongoc:mongoc_collection[7] and linkmongoc:mongoc_database[7] structures
52+
before calling linkmongoc:mongoc_client_destroy[3].
53+
54+
55+
EXAMPLE
56+
-------
57+
58+
The following example connects to a single MongoDB instance and performs a
59+
simple query against it. The resulting documents are printed as 'JSON' to
60+
standard output.
61+
62+
[source,c]
63+
---------------
64+
include::{examples}/example-client.c[]
65+
---------------
66+
67+
68+
SEE ALSO
69+
--------
70+
71+
FUNCTIONS
72+
~~~~~~~~~
73+
74+
linkmongoc:mongoc_client_new[3]
75+
linkmongoc:mongoc_client_new_from_uri[3]
76+
linkmongoc:mongoc_client_destroy[3]
77+
linkmongoc:mongoc_client_set_stream_initiator[3]
78+
linkmongoc:mongoc_client_set_read_prefs[3]
79+
linkmongoc:mongoc_client_set_write_concern[3]
80+
linkmongoc:mongoc_client_get_collection[3]
81+
linkmongoc:mongoc_client_get_database[3]
82+
linkmongoc:mongoc_client_get_gridfs[3]
83+
linkmongoc:mongoc_client_get_read_prefs[3]
84+
linkmongoc:mongoc_client_get_uri[3]
85+
linkmongoc:mongoc_client_get_write_concern[3]
86+
87+
RELATED
88+
~~~~~~~
89+
90+
linkmongoc:mongoc_client_pool[7]
91+
linkmongoc:mongoc_collection[7]
92+
linkmongoc:mongoc_database[7]
93+
94+
95+
AUTHORS
96+
-------
97+
98+
This page was written by MongoDB Inc.

‎doc/mongoc_client_command.txt

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
mongoc_client_command(3)
2+
========================
3+
4+
5+
NAME
6+
----
7+
mongoc_client_command - Executes a command via a client
8+
9+
10+
SYNOPSIS
11+
--------
12+
[source,c]
13+
-----------------------
14+
mongoc_cursor_t *
15+
mongoc_client_command (mongoc_client_t *client,
16+
const char *db,
17+
mongoc_query_flags_t flags,
18+
bson_uint32_t skip,
19+
bson_uint32_t n_return,
20+
const bson_t *query,
21+
const bson_t *fields,
22+
mongoc_read_prefs_t *read_prefs);
23+
24+
bson_bool_t
25+
mongoc_client_command_simple (mongoc_client_t *client,
26+
const char *db,
27+
const bson_t *command,
28+
const mongoc_read_prefs_t *read_prefs,
29+
bson_t *reply,
30+
bson_error_t *error);
31+
-----------------------
32+
33+
34+
DESCRIPTION
35+
-----------
36+
37+
mongoc_client_command()
38+
~~~~~~~~~~~~~~~~~~~~~~~
39+
40+
The _mongoc_client_command()_ function shall execute a command via a client.
41+
This is performed lazily after calling mongoc_cursor_next() on the resulting
42+
cursor structure.
43+
44+
db:: The database to execute the command on
45+
command:: The command to execute
46+
47+
For more on the meaning of the other parameters, see
48+
linkmongoc:mongoc_cursor[7].
49+
50+
mongoc_client_command_simple()
51+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52+
53+
The _mongoc_client_command_simple()_ provides a wrapper around
54+
_mongoc_client_command()_ for simple commands that don't return a cursor.
55+
56+
read_prefs:: read preference for the command
57+
reply:: optional out param for replies
58+
error:: optional location for errors
59+
60+
RETURN VALUE
61+
------------
62+
The _mongoc_client_command()_ function returns a linkmongoc:mongoc_cursor[7].
63+
64+
The _mongoc_client_command_simple()_ function returns true if successful, if
65+
false it sets 'error'.
66+
67+
ERRORS
68+
------
69+
mongoc_client_command()::
70+
errors are detected through active use of the linkmongoc:mongoc_cursor[7].
71+
72+
mongoc_client_command_simple()::
73+
errors may vary based on the command run and the client version.
74+
75+
SEE ALSO
76+
--------
77+
linkmongoc:mongoc_client[7]
78+
linkmongoc:mongoc_cursor[7]
79+
linkmongoc:mongoc_error[7]
80+
81+
82+
AUTHORS
83+
-------
84+
85+
This page was written by MongoDB Inc.

‎doc/mongoc_client_command_simple.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
mongoc_client_command.txt

0 commit comments

Comments
 (0)