From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id B6A7B6DE0ACB for ; Tue, 8 Aug 2017 22:47:39 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Spam-Flag: NO X-Spam-Score: -0.061 X-Spam-Level: X-Spam-Status: No, score=-0.061 tagged_above=-999 required=5 tests=[AWL=-0.061] autolearn=disabled Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 9Fb-CW1CO0lL for ; Tue, 8 Aug 2017 22:47:39 -0700 (PDT) Received: from che.mayfirst.org (che.mayfirst.org [162.247.75.118]) by arlo.cworth.org (Postfix) with ESMTP id D83CA6DE00DB for ; Tue, 8 Aug 2017 22:47:37 -0700 (PDT) Received: from fifthhorseman.net (ool-6c3a0662.static.optonline.net [108.58.6.98]) by che.mayfirst.org (Postfix) with ESMTPSA id 0C32AF99D for ; Wed, 9 Aug 2017 01:47:35 -0400 (EDT) Received: by fifthhorseman.net (Postfix, from userid 1000) id 0D2D220863; Wed, 9 Aug 2017 01:47:31 -0400 (EDT) From: Daniel Kahn Gillmor To: Notmuch Mail Subject: [PATCH 1/3] lib: clarify description of notmuch_database_add_message Date: Wed, 9 Aug 2017 01:47:29 -0400 Message-Id: <20170809054731.23890-1-dkg@fifthhorseman.net> X-Mailer: git-send-email 2.13.2 X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.23 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: Wed, 09 Aug 2017 05:47:39 -0000 Since we're accumulating the index when we add a new file to the message, the semantics have slightly changed. This tries to align the documentation with the actual functionality. --- lib/notmuch.h | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/lib/notmuch.h b/lib/notmuch.h index f78b3473..02586a91 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -542,8 +542,10 @@ notmuch_database_get_directory (notmuch_database_t *database, notmuch_directory_t **directory); /** - * Add a new message to the given notmuch database or associate an - * additional filename with an existing message. + * Add a message file to a database, indexing it for retrieval by + * future searches. If a message already exists with the same message + * ID as the specified file, their indexes will be merged, and this + * new filename will also be associated with the existing message. * * Here, 'filename' should be a path relative to the path of * 'database' (see notmuch_database_get_path), or else should be an @@ -556,8 +558,9 @@ notmuch_database_get_directory (notmuch_database_t *database, * 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. + * database, rather than creating a new message, this adds the search + * terms from the identified file to the existing message's index, and + * adds 'filename' to the list of filenames known for the message. * * If 'message' is not NULL, then, on successful return * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message' -- 2.13.2