[PATCH v2 03/11] lib: Document extent of some return values

diff --git a/03/cceda4830a5662eda2388535326c08fa09377c b/03/cceda4830a5662eda2388535326c08fa09377c
new file mode 100644 (file)
index 0000000..e499ead
--- /dev/null
+++ b/03/cceda4830a5662eda2388535326c08fa09377c
@@ -0,0 +1,103 @@
+Return-Path: <amdragon@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 DC16D421161\r
+       for <notmuch@notmuchmail.org>; Thu, 24 Oct 2013 08:19:33 -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 Do3b0VRLGNqs for <notmuch@notmuchmail.org>;\r
+       Thu, 24 Oct 2013 08:19:29 -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 92FB5429E47\r
+       for <notmuch@notmuchmail.org>; Thu, 24 Oct 2013 08:19:22 -0700 (PDT)\r
+X-AuditID: 12074425-b7f1c8e0000009c7-05-52693a7af5ad\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 F9.31.02503.A7A39625; Thu, 24 Oct 2013 11:19:22 -0400 (EDT)\r
+Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
+       by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id r9OFJF9p012678; \r
+       Thu, 24 Oct 2013 11:19:15 -0400\r
+Received: from drake.dyndns.org\r
+       (216-15-114-40.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com\r
+       [216.15.114.40]) (authenticated bits=0)\r
+       (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+       by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r9OFJC53012911\r
+       (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+       Thu, 24 Oct 2013 11:19:14 -0400\r
+Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
+       (envelope-from <amdragon@mit.edu>)\r
+       id 1VZMgq-0006dn-Na; Thu, 24 Oct 2013 11:19:12 -0400\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH v2 03/11] lib: Document extent of some return values\r
+Date: Thu, 24 Oct 2013 11:19:03 -0400\r
+Message-Id: <1382627951-25252-4-git-send-email-amdragon@mit.edu>\r
+X-Mailer: git-send-email 1.8.4.rc3\r
+In-Reply-To: <1382627951-25252-1-git-send-email-amdragon@mit.edu>\r
+References: <1382627951-25252-1-git-send-email-amdragon@mit.edu>\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFjrKIsWRmVeSWpSXmKPExsUixCmqrFtllRlkcH2TpEXTdGeL1XN5LK7f\r
+       nMnswOyxc9Zddo9b91+zezxbdYs5gDmKyyYlNSezLLVI3y6BK6Nz7ySWgvUcFcdaF7I1MH5g\r
+       62Lk5JAQMJH49P8AlC0mceHeeiCbi0NIYB+jRNsBGGcjo8StqwvZIZw7TBK/L29ihXDmMkqc\r
+       nPAdrJ9NQENi2/7ljCC2iIC0xM67s1lBbGaBaIkjl2cA1XBwCAu4SEz6XgcSZhFQlVjTcpMZ\r
+       xOYVcJC48ew71BlKEgtPbQNr5RRwlPj5+hrYSCGgml+/z7BMYORfwMiwilE2JbdKNzcxM6c4\r
+       NVm3ODkxLy+1SNdCLzezRC81pXQTIyi02F1UdzBOOKR0iFGAg1GJh7fhU3qQEGtiWXFl7iFG\r
+       SQ4mJVHee6aZQUJ8SfkplRmJxRnxRaU5qcWHGCU4mJVEeKfpAeV4UxIrq1KL8mFS0hwsSuK8\r
+       tzjsg4QE0hNLUrNTUwtSi2CyMhwcShK8/yyBGgWLUtNTK9Iyc0oQ0kwcnCDDeYCG3wOp4S0u\r
+       SMwtzkyHyJ9iVJQS5+UFRq+QAEgiozQPrhcW+68YxYFeEeb9ANLOA0wbcN2vgAYzAQ2esiQN\r
+       ZHBJIkJKqoGR79fzkhs7eqWlL6aFJ9/fPnX3fc4M/0Ltn8mv3XfG1zYVs8nkBau9+BYim1e6\r
+       6YryYrHNocEPl6wq/+OVefU/X7f+7lzB0t3vNj33XuYacvjZ2i1brsTq3er0aHEMOOz5Were\r
+       Qaag5hTm40Xbb0qkdS+cP++tRTSb6+ynn/uW3w2IfBh9dssdJZbijERDLeai4kQAPmBYZtgC        AAA=\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: Thu, 24 Oct 2013 15:19:34 -0000\r
+\r
+This documents the extent of the notmuch_messages_t* pointers returned\r
+by notmuch_thread_get_toplevel_messages and\r
+notmuch_thread_get_messages.\r
+---\r
+ lib/notmuch.h | 4 ++++\r
+ 1 file changed, 4 insertions(+)\r
+\r
+diff --git a/lib/notmuch.h b/lib/notmuch.h\r
+index 9dab555..0fb7121 100644\r
+--- a/lib/notmuch.h\r
++++ b/lib/notmuch.h\r
+@@ -765,12 +765,16 @@ notmuch_thread_get_total_messages (notmuch_thread_t *thread);\r
+  * This iterator will not necessarily iterate over all of the messages\r
+  * in the thread. It will only iterate over the messages in the thread\r
+  * which are not replies to other messages in the thread.\r
++ *\r
++ * The returned list will be destroyed when the thread is destroyed.\r
+  */\r
+ notmuch_messages_t *\r
+ notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);\r
+ \r
+ /* Get a notmuch_thread_t iterator for all messages in 'thread' in\r
+  * oldest-first order.\r
++ *\r
++ * The returned list will be destroyed when the thread is destroyed.\r
+  */\r
+ notmuch_messages_t *\r
+ notmuch_thread_get_messages (notmuch_thread_t *thread);\r
+-- \r
+1.8.4.rc3\r
+\r