ba/b8d6d3882b7eda3451990a59c2a9b6263e8c4e

   1 Return-Path: <amthrax@drake.mit.edu>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id DC5E1431FD0\r
   6         for <notmuch@notmuchmail.org>; Sat, 11 Jun 2011 13:07:37 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.7\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
  12         tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id uPqFEaxEDEmD for <notmuch@notmuchmail.org>;\r
  16         Sat, 11 Jun 2011 13:07:37 -0700 (PDT)\r
  17 Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU\r
  18         [18.7.68.37])\r
  19         by olra.theworths.org (Postfix) with ESMTP id 4CCA5431FB6\r
  20         for <notmuch@notmuchmail.org>; Sat, 11 Jun 2011 13:07:37 -0700 (PDT)\r
  21 X-AuditID: 12074425-b7b82ae000000a2a-c9-4df3caf0bda9\r
  22 Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])\r
  23         by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP\r
  24         id D4.75.02602.1FAC3FD4; Sat, 11 Jun 2011 16:07:13 -0400 (EDT)\r
  25 Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
  26         by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id p5BK7afe015106; \r
  27         Sat, 11 Jun 2011 16:07:36 -0400\r
  28 Received: from drake.mit.edu\r
  29         (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com\r
  30         [209.6.116.242]) (authenticated bits=0)\r
  31         (User authenticated as amdragon@ATHENA.MIT.EDU)\r
  32         by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id p5BK7ZUu006088\r
  33         (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
  34         Sat, 11 Jun 2011 16:07:36 -0400 (EDT)\r
  35 Received: from amthrax by drake.mit.edu with local (Exim 4.76)\r
  36         (envelope-from <amthrax@drake.mit.edu>)\r
  37         id 1QVUT1-0000Ik-HC; Sat, 11 Jun 2011 16:07:35 -0400\r
  38 From: Austin Clements <amdragon@MIT.EDU>\r
  39 To: notmuch@notmuchmail.org\r
  40 Subject: [PATCH 17/17] lib: Improve notmuch_database_{add,\r
  41         remove}_message documentation.\r
  42 Date: Sat, 11 Jun 2011 16:04:43 -0400\r
  43 Message-Id: <1307822683-848-18-git-send-email-amdragon@mit.edu>\r
  44 X-Mailer: git-send-email 1.7.5.1\r
  45 In-Reply-To: <1307822683-848-1-git-send-email-amdragon@mit.edu>\r
  46 References: <87ei34rnc5.fsf@yoom.home.cworth.org>\r
  47         <1307822683-848-1-git-send-email-amdragon@mit.edu>\r
  48 X-Brightmail-Tracker:\r
  49  H4sIAAAAAAAAA+NgFjrCIsWRmVeSWpSXmKPExsUixCmqrPvx1Gdfg7132Syu35zJ7MDo8WzV\r
  50         LeYAxigum5TUnMyy1CJ9uwSujGs7nrIXTJSq2Nd/ibWBsVG0i5GTQ0LARKL9wwZmCFtM4sK9\r
  51         9WwgtpDAPkaJeVPUuxi5gOwNjBIfX75lhHDuM0l8nzOZHcKZzyjxuHcSC0gLm4CGxLb9yxlB\r
  52         bBEBaYmdd2ezdjFycDALqEn86VIBCQsLREhcvbyYCcRmEVCVuNh3mxXE5hWwl1hw5jPUFQoS\r
  53         V67MAxvJCRSfd/AqC8RFaRJLbu1mn8DIv4CRYRWjbEpulW5uYmZOcWqybnFyYl5eapGuhV5u\r
  54         ZoleakrpJkZQ0LC7qO5gnHBI6RCjAAejEg+v4trPvkKsiWXFlbmHGCU5mJREeXVOAIX4kvJT\r
  55         KjMSizPii0pzUosPMUpwMCuJ8K5v/+QrxJuSWFmVWpQPk5LmYFES550vqe4rJJCeWJKanZpa\r
  56         kFoEk5Xh4FCS4JUERoeQYFFqempFWmZOCUKaiYMTZDgP0PCjJ4FqeIsLEnOLM9Mh8qcYjTkW\r
  57         rlt/iJHj8YZNhxiFWPLy81KlxHnVQcYJgJRmlObBTYNF/itGcaDnhHkLQap4gEkDbt4roFVM\r
  58         QKsESsFWlSQipKQaGBf/F9r39PJ2kaVrNi18oidhem/2+l8doVmGb1YcOXoxNGjPE/HnxsoF\r
  59         ETG80RFi9+dUmt4WVZdli34ywVPe+zDLifXPUnj1eJsO2bJr/3UsN9m6MMsxUevdvNMNws/D\r
  60         Tt3cEdeYf/DGtsCGspPz57IZSBlJ7UsRu9rfx/Hj8aPKH7+9z9xgP6rEUpyRaKjFXFScCAAp\r
  61         +07Q1wIAAA==\r
  62 Cc: Austin Clements <amdragon@mit.edu>\r
  63 X-BeenThere: notmuch@notmuchmail.org\r
  64 X-Mailman-Version: 2.1.13\r
  65 Precedence: list\r
  66 List-Id: "Use and development of the notmuch mail system."\r
  67         <notmuch.notmuchmail.org>\r
  68 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  69         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  70 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  71 List-Post: <mailto:notmuch@notmuchmail.org>\r
  72 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  73 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  74         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  75 X-List-Received-Date: Sat, 11 Jun 2011 20:07:38 -0000\r
  76 \r
  77 State up front that these functions may add a filename to an existing\r
  78 message or remove only a filename (and not the message), respectively.\r
  79 Previously, this key information was buried in return value\r
  80 documentation or in "notes", which made it seem secondary to these\r
  81 functions' semantics.\r
  82 ---\r
  83  lib/notmuch.h |   25 +++++++++++++++----------\r
  84  1 files changed, 15 insertions(+), 10 deletions(-)\r
  85 \r
  86 diff --git a/lib/notmuch.h b/lib/notmuch.h\r
  87 index 9ae260e..ad62c76 100644\r
  88 --- a/lib/notmuch.h\r
  89 +++ b/lib/notmuch.h\r
  90 @@ -266,9 +266,10 @@ notmuch_directory_t *\r
  91  notmuch_database_get_directory (notmuch_database_t *database,\r
  92                                 const char *path);\r
  93  \r
  94 -/* Add a new message to the given notmuch database.\r
  95 +/* Add a new message to the given notmuch database or associate an\r
  96 + * additional filename with an existing message.\r
  97   *\r
  98 - * Here,'filename' should be a path relative to the path of\r
  99 + * Here, 'filename' should be a path relative to the path of\r
 100   * 'database' (see notmuch_database_get_path), or else should be an\r
 101   * absolute filename with initial components that match the path of\r
 102   * 'database'.\r
 103 @@ -278,6 +279,10 @@ notmuch_database_get_directory (notmuch_database_t *database,\r
 104   * notmuch database will reference the filename, and will not copy the\r
 105   * entire contents of the file.\r
 106   *\r
 107 + * If another message with the same message ID already exists in the\r
 108 + * database, rather than creating a new message, this adds 'filename'\r
 109 + * to the list of the filenames for the existing message.\r
 110 + *\r
 111   * If 'message' is not NULL, then, on successful return\r
 112   * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'\r
 113   * will be initialized to a message object that can be used for things\r
 114 @@ -295,7 +300,7 @@ notmuch_database_get_directory (notmuch_database_t *database,\r
 115   * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message\r
 116   *     ID as another message already in the database. The new\r
 117   *     filename was successfully added to the message in the database\r
 118 - *     (if not already present).\r
 119 + *     (if not already present) and the existing message is returned.\r
 120   *\r
 121   * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the\r
 122   *     file, (such as permission denied, or file not found,\r
 123 @@ -312,14 +317,14 @@ notmuch_database_add_message (notmuch_database_t *database,\r
 124                               const char *filename,\r
 125                               notmuch_message_t **message);\r
 126  \r
 127 -/* Remove a message from the given notmuch database.\r
 128 +/* Remove a message filename from the given notmuch database. If the\r
 129 + * message has no more filenames, remove the message.\r
 130   *\r
 131 - * Note that only this particular filename association is removed from\r
 132 - * the database. If the same message (as determined by the message ID)\r
 133 - * is still available via other filenames, then the message will\r
 134 - * persist in the database for those filenames. When the last filename\r
 135 - * is removed for a particular message, the database content for that\r
 136 - * message will be entirely removed.\r
 137 + * If the same message (as determined by the message ID) is still\r
 138 + * available via other filenames, then the message will persist in the\r
 139 + * database for those filenames. When the last filename is removed for\r
 140 + * a particular message, the database content for that message will be\r
 141 + * entirely removed.\r
 142   *\r
 143   * Return value:\r
 144   *\r
 145 -- \r
 146 1.7.5.1\r
 147 \r