From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id DC5E1431FD0 for ; Sat, 11 Jun 2011 13:07:37 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -0.7 X-Spam-Level: X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id uPqFEaxEDEmD for ; Sat, 11 Jun 2011 13:07:37 -0700 (PDT) Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU [18.7.68.37]) by olra.theworths.org (Postfix) with ESMTP id 4CCA5431FB6 for ; Sat, 11 Jun 2011 13:07:37 -0700 (PDT) X-AuditID: 12074425-b7b82ae000000a2a-c9-4df3caf0bda9 Received: from mailhub-auth-1.mit.edu ( [18.9.21.35]) by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP id D4.75.02602.1FAC3FD4; Sat, 11 Jun 2011 16:07:13 -0400 (EDT) Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id p5BK7afe015106; Sat, 11 Jun 2011 16:07:36 -0400 Received: from drake.mit.edu (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com [209.6.116.242]) (authenticated bits=0) (User authenticated as amdragon@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id p5BK7ZUu006088 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT); Sat, 11 Jun 2011 16:07:36 -0400 (EDT) Received: from amthrax by drake.mit.edu with local (Exim 4.76) (envelope-from ) id 1QVUT1-0000Ik-HC; Sat, 11 Jun 2011 16:07:35 -0400 From: Austin Clements To: notmuch@notmuchmail.org Subject: [PATCH 17/17] lib: Improve notmuch_database_{add, remove}_message documentation. Date: Sat, 11 Jun 2011 16:04:43 -0400 Message-Id: <1307822683-848-18-git-send-email-amdragon@mit.edu> X-Mailer: git-send-email 1.7.5.1 In-Reply-To: <1307822683-848-1-git-send-email-amdragon@mit.edu> References: <87ei34rnc5.fsf@yoom.home.cworth.org> <1307822683-848-1-git-send-email-amdragon@mit.edu> X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFjrCIsWRmVeSWpSXmKPExsUixCmqrPvx1Gdfg7132Syu35zJ7MDo8WzV LeYAxigum5TUnMyy1CJ9uwSujGs7nrIXTJSq2Nd/ibWBsVG0i5GTQ0LARKL9wwZmCFtM4sK9 9WwgtpDAPkaJeVPUuxi5gOwNjBIfX75lhHDuM0l8nzOZHcKZzyjxuHcSC0gLm4CGxLb9yxlB bBEBaYmdd2ezdjFycDALqEn86VIBCQsLREhcvbyYCcRmEVCVuNh3mxXE5hWwl1hw5jPUFQoS V67MAxvJCRSfd/AqC8RFaRJLbu1mn8DIv4CRYRWjbEpulW5uYmZOcWqybnFyYl5eapGuhV5u ZoleakrpJkZQ0LC7qO5gnHBI6RCjAAejEg+v4trPvkKsiWXFlbmHGCU5mJREeXVOAIX4kvJT KjMSizPii0pzUosPMUpwMCuJ8K5v/+QrxJuSWFmVWpQPk5LmYFES550vqe4rJJCeWJKanZpa kFoEk5Xh4FCS4JUERoeQYFFqempFWmZOCUKaiYMTZDgP0PCjJ4FqeIsLEnOLM9Mh8qcYjTkW rlt/iJHj8YZNhxiFWPLy81KlxHnVQcYJgJRmlObBTYNF/itGcaDnhHkLQap4gEkDbt4roFVM QKsESsFWlSQipKQaGBf/F9r39PJ2kaVrNi18oidhem/2+l8doVmGb1YcOXoxNGjPE/HnxsoF ETG80RFi9+dUmt4WVZdli34ywVPe+zDLifXPUnj1eJsO2bJr/3UsN9m6MMsxUevdvNMNws/D Tt3cEdeYf/DGtsCGspPz57IZSBlJ7UsRu9rfx/Hj8aPKH7+9z9xgP6rEUpyRaKjFXFScCAAp +07Q1wIAAA== Cc: Austin Clements X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 11 Jun 2011 20:07:38 -0000 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. --- lib/notmuch.h | 25 +++++++++++++++---------- 1 files changed, 15 insertions(+), 10 deletions(-) diff --git a/lib/notmuch.h b/lib/notmuch.h index 9ae260e..ad62c76 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -266,9 +266,10 @@ notmuch_directory_t * notmuch_database_get_directory (notmuch_database_t *database, 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 * absolute filename with initial components that match the path of * 'database'. @@ -278,6 +279,10 @@ notmuch_database_get_directory (notmuch_database_t *database, * notmuch database will reference the filename, and will not copy the * 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 * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message' * 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 * ID as another message already in the database. The new * 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 * file, (such as permission denied, or file not found, @@ -312,14 +317,14 @@ notmuch_database_add_message (notmuch_database_t *database, const char *filename, 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 - * the database. If the same message (as determined by the message ID) - * is still available via other filenames, then the message will - * persist in the database for those filenames. When the last filename - * is removed for a particular message, the database content for that - * message will be entirely removed. + * If the same message (as determined by the message ID) is still + * available via other filenames, then the message will persist in the + * database for those filenames. When the last filename is removed for + * a particular message, the database content for that message will be + * entirely removed. * * Return value: * -- 1.7.5.1