debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-25 04:18:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

lib: Improve notmuch_database_{add,remove}_message documentation.

Browse source 
State up front that these functions may add a filename to an existing
message or remove only a filename (and not the message), respectively.
Previously, this key information was buried in return value
documentation or in "notes", which made it seem secondary to these
functions' semantics.
This commit is contained in:
Austin Clements 2011-06-11 15:34:11 -04:00 committed by David Bremner
parent bff30540d8
commit 35f4a0f18b
1 changed files with 15 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
lib/notmuch.h
View file

@ -266,7 +266,8 @@ notmuch_directory_t *
notmuch_database_get_directory (notmuch_database_t *database, notmuch_database_get_directory (notmuch_database_t *database,
const char *path); const char *path);
/* Add a new message to the given notmuch database. /* Add a new message to the given notmuch database or associate an
* additional filename with an existing message.
* *
* Here, 'filename' should be a path relative to the path of * Here, 'filename' should be a path relative to the path of
* 'database' (see notmuch_database_get_path), or else should be an * 'database' (see notmuch_database_get_path), or else should be an
@ -278,6 +279,10 @@ notmuch_database_get_directory (notmuch_database_t *database,
* notmuch database will reference the filename, and will not copy the * notmuch database will reference the filename, and will not copy the
* entire contents of the file. * entire contents of the file.
* *
* If another message with the same message ID already exists in the
* database, rather than creating a new message, this adds 'filename'
* to the list of the filenames for the existing message.
*
* If 'message' is not NULL, then, on successful return * If 'message' is not NULL, then, on successful return
* (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message' * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'
* will be initialized to a message object that can be used for things * will be initialized to a message object that can be used for things
@ -295,7 +300,7 @@ notmuch_database_get_directory (notmuch_database_t *database,
* NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
* ID as another message already in the database. The new * ID as another message already in the database. The new
* filename was successfully added to the message in the database * filename was successfully added to the message in the database
* (if not already present). * (if not already present) and the existing message is returned.
* *
* NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
* file, (such as permission denied, or file not found, * file, (such as permission denied, or file not found,
@ -312,14 +317,14 @@ notmuch_database_add_message (notmuch_database_t *database,
const char *filename, const char *filename,
notmuch_message_t **message); notmuch_message_t **message);
/* Remove a message from the given notmuch database. /* Remove a message filename from the given notmuch database. If the
* message has no more filenames, remove the message.
* *
* Note that only this particular filename association is removed from * If the same message (as determined by the message ID) is still
* the database. If the same message (as determined by the message ID) * available via other filenames, then the message will persist in the
* is still available via other filenames, then the message will * database for those filenames. When the last filename is removed for
* persist in the database for those filenames. When the last filename * a particular message, the database content for that message will be
* is removed for a particular message, the database content for that * entirely removed.
* message will be entirely removed.
* *
* Return value: * Return value:
* *