From 0817f0e168c8212200fc6624aeaac77318a9bc35 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Thu, 16 Jun 2011 15:41:48 +0200 Subject: python: Improve API documentation Various API doc cleanups and improvements. No code change. Signed-off-by: Sebastian Spaeth --- bindings/python/docs/source/index.rst | 37 ++++++----------------- bindings/python/docs/source/status_and_errors.rst | 23 ++++++++++++++ 2 files changed, 33 insertions(+), 27 deletions(-) create mode 100644 bindings/python/docs/source/status_and_errors.rst (limited to 'bindings/python/docs') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index d58ba97e..e9f39eb0 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -28,6 +28,7 @@ More information on specific topics can be found on the following pages: .. toctree:: :maxdepth: 1 + status_and_errors notmuch :mod:`notmuch` -- The Notmuch interface @@ -157,7 +158,7 @@ More information on specific topics can be found on the following pages: query. This allows us to distinguish matches from the rest of the messages in that thread. - .. automethod:: get_flag + .. automethod:: get_flag .. automethod:: set_flag @@ -167,6 +168,10 @@ More information on specific topics can be found on the following pages: .. automethod:: get_tags + .. automethod:: maildir_flags_to_tags + + .. automethod:: tags_to_maildir_flags + .. automethod:: remove_tag .. automethod:: add_tag @@ -177,7 +182,9 @@ More information on specific topics can be found on the following pages: .. automethod:: thaw - .. automethod:: format_as_text + .. automethod:: format_message_as_json + + .. automethod:: format_message_as_text .. automethod:: __str__ @@ -252,32 +259,8 @@ More information on specific topics can be found on the following pages: .. autoattribute:: notmuch.database.Directory.path -:exc:`NotmuchError` -- A Notmuch execution error ------------------------------------------------- -.. autoexception:: NotmuchError - :members: - - This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution. - -:class:`STATUS` -- Notmuch operation return status --------------------------------------------------- - -.. data:: STATUS - - STATUS is a class, whose attributes provide constants that serve as return indicators for notmuch functions. Currently the following ones are defined. For possible return values and specific meaning for each method, see the method description. - - * SUCCESS - * OUT_OF_MEMORY - * READ_ONLY_DATABASE - * XAPIAN_EXCEPTION - * FILE_ERROR - * FILE_NOT_EMAIL - * DUPLICATE_MESSAGE_ID - * NULL_POINTER - * TAG_TOO_LONG - * UNBALANCED_FREEZE_THAW - * NOT_INITIALIZED +The `next page `_ contains information on possible Status and Error values. Indices and tables ================== diff --git a/bindings/python/docs/source/status_and_errors.rst b/bindings/python/docs/source/status_and_errors.rst new file mode 100644 index 00000000..1d74ba17 --- /dev/null +++ b/bindings/python/docs/source/status_and_errors.rst @@ -0,0 +1,23 @@ +.. currentmodule:: notmuch + +Status and Errors +================= + +Some methods return a status, indicating if an operation was successful and what the error was. Most of these status codes are expressed as a specific value, the :class:`notmuch.STATUS`. + +:class:`STATUS` -- Notmuch operation return value +-------------------------------------------------- + +.. autoclass:: notmuch.STATUS + :inherited-members: + +.. automethod:: notmuch.STATUS.status2str + +:exc:`NotmuchError` -- A Notmuch execution error +------------------------------------------------ +Whenever an error occurs, we throw a special Exception: + +.. autoexception:: NotmuchError + :members: + + This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution. -- cgit v1.2.3