--- /dev/null
+Return-Path: <amthrax@drake.mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id DC5E1431FD0\r
+ for <notmuch@notmuchmail.org>; Sat, 11 Jun 2011 13:07:37 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id uPqFEaxEDEmD for <notmuch@notmuchmail.org>;\r
+ Sat, 11 Jun 2011 13:07:37 -0700 (PDT)\r
+Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU\r
+ [18.7.68.37])\r
+ by olra.theworths.org (Postfix) with ESMTP id 4CCA5431FB6\r
+ for <notmuch@notmuchmail.org>; Sat, 11 Jun 2011 13:07:37 -0700 (PDT)\r
+X-AuditID: 12074425-b7b82ae000000a2a-c9-4df3caf0bda9\r
+Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])\r
+ by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id D4.75.02602.1FAC3FD4; Sat, 11 Jun 2011 16:07:13 -0400 (EDT)\r
+Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
+ by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id p5BK7afe015106; \r
+ Sat, 11 Jun 2011 16:07:36 -0400\r
+Received: from drake.mit.edu\r
+ (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com\r
+ [209.6.116.242]) (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id p5BK7ZUu006088\r
+ (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+ Sat, 11 Jun 2011 16:07:36 -0400 (EDT)\r
+Received: from amthrax by drake.mit.edu with local (Exim 4.76)\r
+ (envelope-from <amthrax@drake.mit.edu>)\r
+ id 1QVUT1-0000Ik-HC; Sat, 11 Jun 2011 16:07:35 -0400\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH 17/17] lib: Improve notmuch_database_{add,\r
+ remove}_message documentation.\r
+Date: Sat, 11 Jun 2011 16:04:43 -0400\r
+Message-Id: <1307822683-848-18-git-send-email-amdragon@mit.edu>\r
+X-Mailer: git-send-email 1.7.5.1\r
+In-Reply-To: <1307822683-848-1-git-send-email-amdragon@mit.edu>\r
+References: <87ei34rnc5.fsf@yoom.home.cworth.org>\r
+ <1307822683-848-1-git-send-email-amdragon@mit.edu>\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFjrCIsWRmVeSWpSXmKPExsUixCmqrPvx1Gdfg7132Syu35zJ7MDo8WzV\r
+ LeYAxigum5TUnMyy1CJ9uwSujGs7nrIXTJSq2Nd/ibWBsVG0i5GTQ0LARKL9wwZmCFtM4sK9\r
+ 9WwgtpDAPkaJeVPUuxi5gOwNjBIfX75lhHDuM0l8nzOZHcKZzyjxuHcSC0gLm4CGxLb9yxlB\r
+ bBEBaYmdd2ezdjFycDALqEn86VIBCQsLREhcvbyYCcRmEVCVuNh3mxXE5hWwl1hw5jPUFQoS\r
+ V67MAxvJCRSfd/AqC8RFaRJLbu1mn8DIv4CRYRWjbEpulW5uYmZOcWqybnFyYl5eapGuhV5u\r
+ ZoleakrpJkZQ0LC7qO5gnHBI6RCjAAejEg+v4trPvkKsiWXFlbmHGCU5mJREeXVOAIX4kvJT\r
+ KjMSizPii0pzUosPMUpwMCuJ8K5v/+QrxJuSWFmVWpQPk5LmYFES550vqe4rJJCeWJKanZpa\r
+ kFoEk5Xh4FCS4JUERoeQYFFqempFWmZOCUKaiYMTZDgP0PCjJ4FqeIsLEnOLM9Mh8qcYjTkW\r
+ rlt/iJHj8YZNhxiFWPLy81KlxHnVQcYJgJRmlObBTYNF/itGcaDnhHkLQap4gEkDbt4roFVM\r
+ QKsESsFWlSQipKQaGBf/F9r39PJ2kaVrNi18oidhem/2+l8doVmGb1YcOXoxNGjPE/HnxsoF\r
+ ETG80RFi9+dUmt4WVZdli34ywVPe+zDLifXPUnj1eJsO2bJr/3UsN9m6MMsxUevdvNMNws/D\r
+ Tt3cEdeYf/DGtsCGspPz57IZSBlJ7UsRu9rfx/Hj8aPKH7+9z9xgP6rEUpyRaKjFXFScCAAp\r
+ +07Q1wIAAA==\r
+Cc: Austin Clements <amdragon@mit.edu>\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Sat, 11 Jun 2011 20:07:38 -0000\r
+\r
+State up front that these functions may add a filename to an existing\r
+message or remove only a filename (and not the message), respectively.\r
+Previously, this key information was buried in return value\r
+documentation or in "notes", which made it seem secondary to these\r
+functions' semantics.\r
+---\r
+ lib/notmuch.h | 25 +++++++++++++++----------\r
+ 1 files changed, 15 insertions(+), 10 deletions(-)\r
+\r
+diff --git a/lib/notmuch.h b/lib/notmuch.h\r
+index 9ae260e..ad62c76 100644\r
+--- a/lib/notmuch.h\r
++++ b/lib/notmuch.h\r
+@@ -266,9 +266,10 @@ notmuch_directory_t *\r
+ notmuch_database_get_directory (notmuch_database_t *database,\r
+ const char *path);\r
+ \r
+-/* Add a new message to the given notmuch database.\r
++/* Add a new message to the given notmuch database or associate an\r
++ * additional filename with an existing message.\r
+ *\r
+- * Here,'filename' should be a path relative to the path of\r
++ * Here, 'filename' should be a path relative to the path of\r
+ * 'database' (see notmuch_database_get_path), or else should be an\r
+ * absolute filename with initial components that match the path of\r
+ * 'database'.\r
+@@ -278,6 +279,10 @@ notmuch_database_get_directory (notmuch_database_t *database,\r
+ * notmuch database will reference the filename, and will not copy the\r
+ * entire contents of the file.\r
+ *\r
++ * If another message with the same message ID already exists in the\r
++ * database, rather than creating a new message, this adds 'filename'\r
++ * to the list of the filenames for the existing message.\r
++ *\r
+ * If 'message' is not NULL, then, on successful return\r
+ * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'\r
+ * will be initialized to a message object that can be used for things\r
+@@ -295,7 +300,7 @@ notmuch_database_get_directory (notmuch_database_t *database,\r
+ * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message\r
+ * ID as another message already in the database. The new\r
+ * filename was successfully added to the message in the database\r
+- * (if not already present).\r
++ * (if not already present) and the existing message is returned.\r
+ *\r
+ * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the\r
+ * file, (such as permission denied, or file not found,\r
+@@ -312,14 +317,14 @@ notmuch_database_add_message (notmuch_database_t *database,\r
+ const char *filename,\r
+ notmuch_message_t **message);\r
+ \r
+-/* Remove a message from the given notmuch database.\r
++/* Remove a message filename from the given notmuch database. If the\r
++ * message has no more filenames, remove the message.\r
+ *\r
+- * Note that only this particular filename association is removed from\r
+- * the database. If the same message (as determined by the message ID)\r
+- * is still available via other filenames, then the message will\r
+- * persist in the database for those filenames. When the last filename\r
+- * is removed for a particular message, the database content for that\r
+- * message will be entirely removed.\r
++ * If the same message (as determined by the message ID) is still\r
++ * available via other filenames, then the message will persist in the\r
++ * database for those filenames. When the last filename is removed for\r
++ * a particular message, the database content for that message will be\r
++ * entirely removed.\r
+ *\r
+ * Return value:\r
+ *\r
+-- \r
+1.7.5.1\r
+\r
projects / notmuch-archives.git / commitdiff