[PATCH] Improve developer documentation

[Sebastian Spaeth]

Well, this patch... improves it. :)

Signed-off-by: Sebastian Spaeth <Sebastian at SSpaeth.de>
---
 docs/dev-doc-src/index.rst      |   15 ++++++++-------
 docs/dev-doc-src/repository.rst |    4 ++--
 docs/dev-doc-src/ui.rst         |    2 +-
 offlineimap/error.py            |   15 +++++++++------
 4 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/docs/dev-doc-src/index.rst b/docs/dev-doc-src/index.rst
index f4d7067..7cf27e2 100644
--- a/docs/dev-doc-src/index.rst
+++ b/docs/dev-doc-src/index.rst
@@ -5,9 +5,9 @@
 Welcome to :mod:`offlineimaps`'s documentation
 ==============================================
 
-The :mod:`offlineimap` module provides the user interface for synchronization between IMAP servers and MailDirs or between IMAP servers. The homepage containing the source code repository can be found at the `offlineimap homepage <http://offlineimap.org>`_.
+The :mod:`offlineimap` module provides the user interface for synchronization between IMAP servers and MailDirs or between IMAP servers. The homepage containing the source code repository can be found at the `offlineimap homepage <http://offlineimap.org>`_. The following provides the developer documentation for those who are interested in modifying the source code or otherwise peek into the OfflineImap internals. End users might want to check the MANUAL, our INSTALLation instructions, and the FAQ.
 
-Within :mod:`offlineimap`, the classes :class:`OfflineImap` provides the high-level functionality. The rest of the classes should usually not needed to be touched by the user. A folder is represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative :mod:`offlineimap.folder`.
+Within :mod:`offlineimap`, the classes :class:`OfflineImap` provides the high-level functionality. The rest of the classes should usually not needed to be touched by the user. Email repositories are represented by a :class:`offlineimap.repository.Base.BaseRepository` or derivatives (see :mod:`offlineimap.repository` for details). A folder within a repository is represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative from :mod:`offlineimap.folder`.
 
 .. moduleauthor:: John Goerzen, and many others. See AUTHORS and the git history for a full list.
 
@@ -15,7 +15,7 @@ Within :mod:`offlineimap`, the classes :class:`OfflineImap` provides the high-le
 
 This page contains the main API overview of OfflineImap |release|. 
 
-Notmuch can be imported as::
+OfflineImap can be imported as::
 
  from offlineimap import OfflineImap
 
@@ -58,11 +58,12 @@ An :class:`accounts.Account` connects two email repositories that are to be sync
 
       Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
 
-
-:exc:`OfflineImapException` -- A Notmuch execution error
+:exc:`OfflineImapError` -- A Notmuch execution error
 --------------------------------------------------------
 
-.. autoexception:: offlineimap.OfflineImapException
+.. autoexception:: offlineimap.error.OfflineImapError
    :members:
 
-   This execption inherits directly from :exc:`Exception` and is raised on errors during the offlineimap execution.
+   This execption inherits directly from :exc:`Exception` and is raised
+   on errors during the offlineimap execution. It has an attribute
+   `severity` that denotes the severity level of the error.
diff --git a/docs/dev-doc-src/repository.rst b/docs/dev-doc-src/repository.rst
index 04025cd..1594a68 100644
--- a/docs/dev-doc-src/repository.rst
+++ b/docs/dev-doc-src/repository.rst
@@ -25,8 +25,8 @@ on your configuration. So when you want to instanciate a new
 
 
 
-:mod:`offlineimap.repository` -- Basic representation of a mail repository
---------------------------------------------------------------------------
+:mod:`offlineimap.repository.Base.BaseRepository` -- Representation of a mail repository
+------------------------------------------------------------------------------------------
 .. autoclass:: offlineimap.repository.Base.BaseRepository
    :members:
    :inherited-members:
diff --git a/docs/dev-doc-src/ui.rst b/docs/dev-doc-src/ui.rst
index 03da19b..27be221 100644
--- a/docs/dev-doc-src/ui.rst
+++ b/docs/dev-doc-src/ui.rst
@@ -1,4 +1,4 @@
-:mod:`offlineimap.ui` -- A pluggable logging system
+:mod:`offlineimap.ui` -- A flexible logging system
 --------------------------------------------------------
 
 .. currentmodule:: offlineimap.ui
diff --git a/offlineimap/error.py b/offlineimap/error.py
index d4d16be..9e55162 100644
--- a/offlineimap/error.py
+++ b/offlineimap/error.py
@@ -2,11 +2,14 @@ class OfflineImapError(Exception):
     """An Error during offlineimap synchronization"""
 
     class ERROR:
-        """Severity levels"""
-        MESSAGE  = 0
-        FOLDER   = 10
-        REPO     = 20
-        CRITICAL = 30
+        """Severity level of an Exception
+
+        * **MESSAGE**:  Abort the current message, but continue with folder
+        * **FOLDER**:   Abort folder sync, but continue with next folder
+        * **REPO**:     Abort repository sync, continue with next account
+        * **CRITICAL**: Immediately exit offlineimap
+        """
+        MESSAGE, FOLDER, REPO, CRITICAL = 0, 10, 20, 30
 
     def __init__(self, reason, severity, errcode=None):
         """
@@ -17,7 +20,7 @@ class OfflineImapError(Exception):
                message, but a ERROR.REPO occurs when the server is
                offline.
 
-         :param errcode: optional number denoting a predefined error
+        :param errcode: optional number denoting a predefined error
                situation (which let's us exit with a predefined exit
                value). So far, no errcodes have been defined yet.
 
-- 
1.7.4.1