many doc improvements, fixed at least one bug due to parameter renaming

4 files changed, 80 insertions, 60 deletions

diff --git a/cnotmuch/__init__.py b/cnotmuch/__init__.py
index e24dc96..e69de29 100644
--- a/cnotmuch/__init__.py
+++ b/cnotmuch/__init__.py
@@ -1,3 +0,0 @@
-__version__=0.1
-__author__ ="Sebastian Spaeth <Sebastian@SSpaeth.de>"
-#ctypes.util.find_library("notmuch")
diff --git a/cnotmuch/database.py b/cnotmuch/database.py
index eb54626..2b51e5e 100644
--- a/cnotmuch/database.py
+++ b/cnotmuch/database.py
@@ -7,31 +7,11 @@ from datetime import date
 class Database(object):
     """Represents a notmuch database (wraps notmuch_database_t)
 
-    .. note:: Do note that as soon as we tear down this object, all underlying 
-           derived objects such as queries, threads, messages, tags etc will 
-           be freed by the underlying library as well. Accessing these objects
-           will lead to segfaults and other unexpected behavior.
-
-           We implement reference counting, so that parent objects can be 
-           automatically freed when they are not needed anymore, for example::
-
-            db = Database('path',create=True)
-            msgs = Query(db,'from:myself').search_messages()
-
-           This returns a :class:`Messages` which internally contains
-           a reference to the parent :class:`Query` object. Otherwise
-           the Query() would be immediately freed, taking our *msgs*
-           down with it.
-
-           In this case, the above Query() object will be
-           automatically freed whenever we delete all derived objects,
-           ie in our case: `del (msgs)` would also delete the parent
-           Query (but not the parent Database() as that is still
-           referenced from the variable *db* in which it is stored.
-
-           Pretty much the same is valid for all other objects in the hierarchy,
-           such as :class:`Query`, :class:`Messages`, :class:`Message`,
-           and :class:`Tags`.
+    .. note:: Do remember that as soon as we tear down this object,
+           all underlying derived objects such as queries, threads,
+           messages, tags etc will be freed by the underlying library
+           as well. Accessing these objects will lead to segfaults and
+           other unexpected behavior. See above for more details.
     """
     MODE = Enum(['READ_ONLY','READ_WRITE'])
     """Constants: Mode in which to open the database"""
@@ -63,8 +43,7 @@ class Database(object):
         """If *path* is *None*, we will try to read a users notmuch
         configuration and use his default database. If *create* is `True`,
         the database will always be created in
-        :attr:`MODE.READ_WRITE` mode as creating an empty
-        database for reading only does not make a great deal of sense.
+        :attr:`MODE`.READ_WRITE mode.
 
         :param path:   Directory to open/create the database in (see
                        above for behavior if `None`)
@@ -72,7 +51,7 @@ class Database(object):
         :param create: False to open an existing, True to create a new
                        database.  
         :type create:  bool
-        :param mdoe:   Mode to open a database in. Always 
+        :param mode:   Mode to open a database in. Always 
                        :attr:`MODE`.READ_WRITE when creating a new one.
         :type mode:    :attr:`MODE`
         :returns:      Nothing
@@ -87,17 +66,19 @@ class Database(object):
             path = Database._std_db_path
 
         if create == False:
-            self.open(path, status)
+            self.open(path, mode)
         else:
             self.create(path)
 
     def create(self, path):
         """Creates a new notmuch database
 
-        This function wraps *notmuch_database_create(...)* and creates
-        a new notmuch database at *path*. It will always return a database in
-        :attr:`MODE`.READ_WRITE mode as creating an empty database 
-        for reading only does not make a great deal of sense.
+        This function is used by __init__() usually does not need
+        to be called directly. It wraps the underlying
+        *notmuch_database_create* function and creates a new notmuch
+        database at *path*. It will always return a database in
+        :attr:`MODE`.READ_WRITE mode as creating an empty database for
+        reading only does not make a great deal of sense.
 
         :param path: A directory in which we should create the database.
         :type path: str
@@ -116,14 +97,21 @@ class Database(object):
                 message="Could not create the specified database")
         self._db = res
 
-    def open(self, path, status= MODE.READ_ONLY): 
-        """calls notmuch_database_open
+    def open(self, path, mode= MODE.READ_ONLY): 
+        """Opens an existing database
 
-        :returns: Raises :exc:`notmuch.NotmuchError` in case
-                  of any failure (after printing an error message on stderr).
+        This function is used by __init__() usually does not need
+        to be called directly. It wraps the underlying
+        *notmuch_database_open* function.
+
+        :param status: Open the database in read-only or read-write mode
+        :type status:  :attr:`MODE` 
+        :returns: Nothing
+        :exception: Raises :exc:`notmuch.NotmuchError` in case
+                    of any failure (after printing an error message on stderr).
         """
 
-        res = Database._open(path, status)
+        res = Database._open(path, mode)
 
         if res is None:
             raise NotmuchError(
@@ -131,11 +119,15 @@ class Database(object):
         self._db = res
 
     def get_path(self):
-        """notmuch_database_get_path (notmuch_database_t *database);  """
+        """Returns the file path of an open database
+
+        Wraps notmuch_database_get_path"""
         return Database._get_path(self._db)
 
     def find_message(self, msgid):
-        """notmuch_database_find_message
+        """Returns a :class:`Message` as identified by its message ID
+
+        wraps *notmuch_database_find_message*
 
         :param msgid: The message id
         :type msgid: string
diff --git a/cnotmuch/notmuch.py b/cnotmuch/notmuch.py
index 4bf593a..e945d49 100644
--- a/cnotmuch/notmuch.py
+++ b/cnotmuch/notmuch.py
@@ -1,12 +1,42 @@
+"""The :mod:`notmuch` module provides most of the functionality that a user is likely to need.
+
+.. note:: The underlying notmuch library is build on a hierarchical
+    memory allocator called talloc. All objects derive from a
+    top-level :class:`Database` object.
+    
+    This means that as soon as an object is deleted, all underlying
+    derived objects such as Queries, Messages, Message, and Tags will
+    be freed by the underlying library as well. Accessing these
+    objects will then lead to segfaults and other unexpected behavior.
+
+    We implement reference counting, so that parent objects can be
+    automatically freed when they are not needed anymore. For
+    example::
+
+            db = Database('path',create=True)
+            msgs = Query(db,'from:myself').search_messages()
+
+    This returns a :class:`Messages` which internally contains a
+    reference to its parent :class:`Query` object. Otherwise the
+    Query() would be immediately freed, taking our *msgs* down with
+    it.
+
+    In this case, the above Query() object will be automatically freed
+    whenever we delete all derived objects, ie in our case:
+    `del(msgs)` would also delete the parent Query (but not the parent
+    Database() as that is still referenced from the variable *db* in
+    which it is stored.
+
+    Pretty much the same is valid for all other objects in the
+    hierarchy, such as :class:`Query`, :class:`Messages`,
+    :class:`Message`, and :class:`Tags`.
+
+"""
 import ctypes
 from ctypes import c_int, c_char_p
 from database import Database,Tags,Query,Messages,Message,Tags
 from cnotmuch.globals import nmlib,STATUS,NotmuchError
+__LICENSE__="GPL v3+"
+__VERSION__=0.1
+__AUTHOR__ ="Sebastian Spaeth <Sebastian@SSpaeth.de>"
 
-# 114 typedef struct _notmuch_query notmuch_query_t;
-# 115 typedef struct _notmuch_threads notmuch_threads_t;
-# 116 typedef struct _notmuch_thread notmuch_thread_t;
-# 117 typedef struct _notmuch_messages notmuch_messages_t;
-# 118 typedef struct _notmuch_message notmuch_message_t;
-# 120 typedef struct _notmuch_directory notmuch_directory_t;
-# 121 typedef struct _notmuch_filenames notmuch_filenames_t;
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 06f2142..d6f9411 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,13 +1,13 @@
 .. cnotmuch documentation master file, created by
    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
 
-.. currentmodule:: cnotmuch.notmuch
+.. currentmodule:: cnotmuch
 
-Welcome to notmuch's documentation!
-===================================
+Welcome to :mod:`cnotmuch`'s documentation
+===========================================
 
 The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
-The classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Messages` and :class:`Tags`.
+The classes :class:`notmuch.Database`, :class:`notmuch.Query` provide most of the core functionality, returning :class:`notmuch.Messages` and :class:`notmuch.Tags`.
 
 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
 
@@ -15,11 +15,11 @@ The classes :class:`Database`, :class:`Query` provide most of the core functiona
 
 This page contains the main API overview. More information on specific topics can be found on the following pages: (none here yet)
 
-Notmuch can be imported as:
+Notmuch can be imported as::
 
  from cnotmuch import notmuch
 
-or:
+or::
 
  from cnotmuch.notmuch import Query,Database
 
@@ -27,11 +27,12 @@ or:
    :maxdepth: 1
 
 
-
 :mod:`notmuch` -- The Notmuch interface
 =============================================
 
-Document from cnotmuch.globals import nmlib,STATUS
+.. automodule:: cnotmuch.notmuch
+
+:todo: Document nmlib,STATUS
 
 :class:`Database` -- The underlying notmuch database
 -----------------------------------------------------
@@ -53,10 +54,10 @@ Document from cnotmuch.globals import nmlib,STATUS
 
      Defines constants that are used as the mode in which to open a database.
 
-     READ_ONLY
+     MODE.READ_ONLY
        Open the database in read-only mode
 
-     READ_WRITE
+     MODE.READ_WRITE
        Open the database in read-write mode
 
    .. autoattribute:: db_p