From: laochailan Date: Sun, 31 May 2015 12:02:13 +0000 (+0200) Subject: [PATCH 3/5] formatted comments for better godoc output X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=fbb7f92b9fd8011edbed3abba891e14df39ad6ab;p=notmuch-archives.git [PATCH 3/5] formatted comments for better godoc output --- diff --git a/4b/329f03e9b14377f9cedca5be4cbf58b6ca31de b/4b/329f03e9b14377f9cedca5be4cbf58b6ca31de new file mode 100644 index 000000000..476b28510 --- /dev/null +++ b/4b/329f03e9b14377f9cedca5be4cbf58b6ca31de @@ -0,0 +1,1806 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by arlo.cworth.org (Postfix) with ESMTP id 1CFBE6DE179E + for ; Sun, 31 May 2015 05:23:01 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at cworth.org +X-Spam-Flag: NO +X-Spam-Score: 1.047 +X-Spam-Level: * +X-Spam-Status: No, score=1.047 tagged_above=-999 required=5 tests=[AWL=-1.613, + FREEMAIL_FROM=0.001, RCVD_IN_SBL=2.596, RCVD_IN_SORBS_WEB=0.614, + RP_MATCHES_RCVD=-0.55, SPF_PASS=-0.001] 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 gRHAhN6jkKiC for ; + Sun, 31 May 2015 05:22:57 -0700 (PDT) +X-Greylist: delayed 1205 seconds by postgrey-1.35 at arlo; + Sun, 31 May 2015 05:22:57 PDT +Received: from mout-xforward.web.de (mout-xforward.web.de [82.165.159.2]) + by arlo.cworth.org (Postfix) with ESMTPS id 18E6E6DE179D + for ; Sun, 31 May 2015 05:22:56 -0700 (PDT) +Received: from localhost ([92.204.48.23]) by smtp.web.de (mrweb003) with + ESMTPSA (Nemesis) id 0Lb289-1ZNKCn1RcH-00kiHW; Sun, 31 May 2015 14:02:49 + +0200 +From: laochailan +To: notmuch@notmuchmail.org +Subject: [PATCH 3/5] formatted comments for better godoc output +Date: Sun, 31 May 2015 14:02:13 +0200 +Message-Id: <1433073735-7721-4-git-send-email-laochailan@web.de> +X-Mailer: git-send-email 2.4.2 +In-Reply-To: <1433073735-7721-1-git-send-email-laochailan@web.de> +References: <1433073735-7721-1-git-send-email-laochailan@web.de> +X-Provags-ID: V03:K0:5DP/+TyWYqHgWlnUxz3vyH8oCHc/vg8TI/7ZTNFbHWrqf1aMYHr + WRXyesRh43muG+tkaxcX88Ub+1bo54RfCo6auUtoHMvhKgTX0SdjCjwSx0HxG/kUt43txmT + hR6ztazo9M1Y6Aee8fTMcCnpv7bFbgx5eIXsolRcdvLhAJn7Ka4qEzQldK5U1WS4hVPYDb1 + fxtqKSjyJQx174ya6IjMQ== +X-UI-Out-Filterresults: junk:10; +X-Mailman-Approved-At: Mon, 01 Jun 2015 09:14:44 -0700 +Cc: laochailan +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.18 +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: Sun, 31 May 2015 12:23:01 -0000 + +before it looked like this +http://godoc.org/github.com/notmuch/notmuch/bindings/go/src/notmuch#Database.RemoveMessage +--- + bindings/go/src/notmuch/notmuch.go | 1325 +++++++++++++++++------------------- + 1 file changed, 632 insertions(+), 693 deletions(-) + +diff --git a/bindings/go/src/notmuch/notmuch.go b/bindings/go/src/notmuch/notmuch.go +index bffc120..741fabf 100644 +--- a/bindings/go/src/notmuch/notmuch.go ++++ b/bindings/go/src/notmuch/notmuch.go +@@ -44,8 +44,8 @@ func (self Status) String() string { + return "" + } + +-/* Various opaque data types. For each notmuch__t see the various +- * notmuch_ functions below. */ ++// Various opaque data types. For each notmuch__t see the various ++// notmuch_ functions below. + + type Database struct { + db *C.notmuch_database_t +@@ -108,23 +108,22 @@ func NewDatabase(path string) (*Database, Status) { + return self, st + } + +-/* Open an existing notmuch database located at 'path'. +- * +- * The database should have been created at some time in the past, +- * (not necessarily by this process), by calling +- * notmuch_database_create with 'path'. By default the database should be +- * opened for reading only. In order to write to the database you need to +- * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode. +- * +- * An existing notmuch database can be identified by the presence of a +- * directory named ".notmuch" below 'path'. +- * +- * The caller should call notmuch_database_destroy when finished with +- * this database. +- * +- * In case of any failure, this function returns NULL, (after printing +- * an error message on stderr). +- */ ++// Open an existing notmuch database located at 'path'. ++// ++// The database should have been created at some time in the past, ++// (not necessarily by this process), by calling ++// notmuch_database_create with 'path'. By default the database should be ++// opened for reading only. In order to write to the database you need to ++// pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode. ++// ++// An existing notmuch database can be identified by the presence of a ++// directory named ".notmuch" below 'path'. ++// ++// The caller should call notmuch_database_destroy when finished with ++// this database. ++// ++// In case of any failure, this function returns NULL, (after printing ++// an error message on stderr). + func OpenDatabase(path string, mode DatabaseMode) (*Database, Status) { + + var c_path *C.char = C.CString(path) +@@ -142,14 +141,13 @@ func OpenDatabase(path string, mode DatabaseMode) (*Database, Status) { + return self, st + } + +-/* Close the given notmuch database, freeing all associated +- * resources. See notmuch_database_open. */ ++// Close the given notmuch database, freeing all associated ++// resources. See notmuch_database_open. + func (self *Database) Close() Status { + return Status(C.notmuch_database_destroy(self.db)) + } + +-/* Return the database path of the given database. +- */ ++// Return the database path of the given database. + func (self *Database) GetPath() string { + + /* The return value is a string owned by notmuch so should not be +@@ -162,17 +160,17 @@ func (self *Database) GetPath() string { + return "" + } + +-/* Return the database format version of the given database. */ ++// Return the database format version of the given database. + func (self *Database) GetVersion() uint { + return uint(C.notmuch_database_get_version(self.db)) + } + +-/* Does this database need to be upgraded before writing to it? +- * +- * If this function returns TRUE then no functions that modify the +- * database (notmuch_database_add_message, notmuch_message_add_tag, +- * notmuch_directory_set_mtime, etc.) will work unless the function +- * notmuch_database_upgrade is called successfully first. */ ++// Does this database need to be upgraded before writing to it? ++// ++// If this function returns TRUE then no functions that modify the ++// database (notmuch_database_add_message, notmuch_message_add_tag, ++// notmuch_directory_set_mtime, etc.) will work unless the function ++// notmuch_database_upgrade is called successfully first. + func (self *Database) NeedsUpgrade() bool { + do_upgrade := C.notmuch_database_needs_upgrade(self.db) + if do_upgrade == 0 { +@@ -183,14 +181,13 @@ func (self *Database) NeedsUpgrade() bool { + + // TODO: notmuch_database_upgrade + +-/* Retrieve a directory object from the database for 'path'. +- * +- * Here, 'path' should be a path relative to the path of 'database' +- * (see notmuch_database_get_path), or else should be an absolute path +- * with initial components that match the path of 'database'. +- * +- * Can return NULL if a Xapian exception occurs. +- */ ++// Retrieve a directory object from the database for 'path'. ++// ++// Here, 'path' should be a path relative to the path of 'database' ++// (see notmuch_database_get_path), or else should be an absolute path ++// with initial components that match the path of 'database'. ++// ++// Can return NULL if a Xapian exception occurs. + func (self *Database) GetDirectory(path string) (*Directory, Status) { + var c_path *C.char = C.CString(path) + defer C.free(unsafe.Pointer(c_path)) +@@ -207,46 +204,45 @@ func (self *Database) GetDirectory(path string) (*Directory, Status) { + return &Directory{dir: c_dir}, st + } + +-/* Add a new message to the given notmuch database. +- * +- * 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'. +- * +- * The file should be a single mail message (not a multi-message mbox) +- * that is expected to remain at its current location, (since the +- * notmuch database will reference the filename, and will not copy the +- * entire contents of the file. +- * +- * If 'message' is not NULL, then, on successful return '*message' +- * will be initialized to a message object that can be used for things +- * such as adding tags to the just-added message. The user should call +- * notmuch_message_destroy when done with the message. On any failure +- * '*message' will be set to NULL. +- * +- * Return value: +- * +- * NOTMUCH_STATUS_SUCCESS: Message successfully added to database. +- * +- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, +- * message not added. +- * +- * 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). +- * +- * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the +- * file, (such as permission denied, or file not found, +- * etc.). Nothing added to the database. +- * +- * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look +- * like an email message. Nothing added to the database. +- * +- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only +- * mode so no message can be added. +- */ ++// Add a new message to the given notmuch database. ++// ++// 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'. ++// ++// The file should be a single mail message (not a multi-message mbox) ++// that is expected to remain at its current location, (since the ++// notmuch database will reference the filename, and will not copy the ++// entire contents of the file. ++// ++// If 'message' is not NULL, then, on successful return '*message' ++// will be initialized to a message object that can be used for things ++// such as adding tags to the just-added message. The user should call ++// notmuch_message_destroy when done with the message. On any failure ++// '*message' will be set to NULL. ++// ++// Return value: ++// ++// NOTMUCH_STATUS_SUCCESS: Message successfully added to database. ++// ++// NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, ++// message not added. ++// ++// 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). ++// ++// NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the ++// file, (such as permission denied, or file not found, ++// etc.). Nothing added to the database. ++// ++// NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look ++// like an email message. Nothing added to the database. ++// ++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only ++// mode so no message can be added. + func (self *Database) AddMessage(fname string) (*Message, Status) { + var c_fname *C.char = C.CString(fname) + defer C.free(unsafe.Pointer(c_fname)) +@@ -261,30 +257,29 @@ func (self *Database) AddMessage(fname string) (*Message, Status) { + return &Message{message: c_msg}, st + } + +-/* Remove a message from the given notmuch database. +- * +- * 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. +- * +- * Return value: +- * +- * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the +- * message was removed from the database. +- * +- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, +- * message not removed. +- * +- * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but +- * the message persists in the database with at least one other +- * filename. +- * +- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only +- * mode so no message can be removed. +- */ ++// Remove a message from the given notmuch database. ++// ++// 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. ++// ++// Return value: ++// ++// NOTMUCH_STATUS_SUCCESS: The last filename was removed and the ++// message was removed from the database. ++// ++// NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, ++// message not removed. ++// ++// NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but ++// the message persists in the database with at least one other ++// filename. ++// ++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only ++// mode so no message can be removed. + func (self *Database) RemoveMessage(fname string) Status { + + var c_fname *C.char = C.CString(fname) +@@ -298,18 +293,17 @@ func (self *Database) RemoveMessage(fname string) Status { + return Status(st) + } + +-/* Find a message with the given message_id. +- * +- * If the database contains a message with the given message_id, then +- * a new notmuch_message_t object is returned. The caller should call +- * notmuch_message_destroy when done with the message. +- * +- * This function returns NULL in the following situations: +- * +- * * No message is found with the given message_id +- * * An out-of-memory situation occurs +- * * A Xapian exception occurs +- */ ++// Find a message with the given message_id. ++// ++// If the database contains a message with the given message_id, then ++// a new notmuch_message_t object is returned. The caller should call ++// notmuch_message_destroy when done with the message. ++// ++// This function returns NULL in the following situations: ++// ++// * No message is found with the given message_id ++// * An out-of-memory situation occurs ++// * A Xapian exception occurs + func (self *Database) FindMessage(message_id string) (*Message, Status) { + + var c_msg_id *C.char = C.CString(message_id) +@@ -327,13 +321,12 @@ func (self *Database) FindMessage(message_id string) (*Message, Status) { + return msg, st + } + +-/* Return a list of all tags found in the database. +- * +- * This function creates a list of all tags found in the database. The +- * resulting list contains all tags from all messages found in the database. +- * +- * On error this function returns NULL. +- */ ++// Return a list of all tags found in the database. ++// ++// This function creates a list of all tags found in the database. The ++// resulting list contains all tags from all messages found in the database. ++// ++// On error this function returns NULL. + func (self *Database) GetAllTags() *Tags { + tags := C.notmuch_database_get_all_tags(self.db) + if tags == nil { +@@ -342,30 +335,29 @@ func (self *Database) GetAllTags() *Tags { + return &Tags{tags: tags} + } + +-/* Create a new query for 'database'. +- * +- * Here, 'database' should be an open database, (see +- * notmuch_database_open and notmuch_database_create). +- * +- * For the query string, we'll document the syntax here more +- * completely in the future, but it's likely to be a specialized +- * version of the general Xapian query syntax: +- * +- * http://xapian.org/docs/queryparser.html +- * +- * As a special case, passing either a length-zero string, (that is ""), +- * or a string consisting of a single asterisk (that is "*"), will +- * result in a query that returns all messages in the database. +- * +- * See notmuch_query_set_sort for controlling the order of results. +- * See notmuch_query_search_messages and notmuch_query_search_threads +- * to actually execute the query. +- * +- * User should call notmuch_query_destroy when finished with this +- * query. +- * +- * Will return NULL if insufficient memory is available. +- */ ++// Create a new query for 'database'. ++// ++// Here, 'database' should be an open database, (see ++// notmuch_database_open and notmuch_database_create). ++// ++// For the query string, we'll document the syntax here more ++// completely in the future, but it's likely to be a specialized ++// version of the general Xapian query syntax: ++// ++// http://xapian.org/docs/queryparser.html ++// ++// As a special case, passing either a length-zero string, (that is ""), ++// or a string consisting of a single asterisk (that is "*"), will ++// result in a query that returns all messages in the database. ++// ++// See notmuch_query_set_sort for controlling the order of results. ++// See notmuch_query_search_messages and notmuch_query_search_threads ++// to actually execute the query. ++// ++// User should call notmuch_query_destroy when finished with this ++// query. ++// ++// Will return NULL if insufficient memory is available. + func (self *Database) CreateQuery(query string) *Query { + + var c_query *C.char = C.CString(query) +@@ -382,7 +374,7 @@ func (self *Database) CreateQuery(query string) *Query { + return &Query{query: q} + } + +-/* Sort values for notmuch_query_set_sort */ ++// Sort values for notmuch_query_set_sort + type Sort C.notmuch_sort_t + + const ( +@@ -392,7 +384,7 @@ const ( + SORT_UNSORTED + ) + +-/* Return the query_string of this query. See notmuch_query_create. */ ++// Return the query_string of this query. See notmuch_query_create. + func (self *Query) String() string { + // FIXME: do we own 'q' or not ? + q := C.notmuch_query_get_query_string(self.query) +@@ -406,54 +398,53 @@ func (self *Query) String() string { + return "" + } + +-/* Specify the sorting desired for this query. */ ++// Specify the sorting desired for this query. + func (self *Query) SetSort(sort Sort) { + C.notmuch_query_set_sort(self.query, C.notmuch_sort_t(sort)) + } + +-/* Return the sort specified for this query. See notmuch_query_set_sort. */ ++// Return the sort specified for this query. See notmuch_query_set_sort. + func (self *Query) GetSort() Sort { + return Sort(C.notmuch_query_get_sort(self.query)) + } + +-/* Execute a query for threads, returning a notmuch_threads_t object +- * which can be used to iterate over the results. The returned threads +- * object is owned by the query and as such, will only be valid until +- * notmuch_query_destroy. +- * +- * Typical usage might be: +- * +- * notmuch_query_t *query; +- * notmuch_threads_t *threads; +- * notmuch_thread_t *thread; +- * +- * query = notmuch_query_create (database, query_string); +- * +- * for (threads = notmuch_query_search_threads (query); +- * notmuch_threads_valid (threads); +- * notmuch_threads_move_to_next (threads)) +- * { +- * thread = notmuch_threads_get (threads); +- * .... +- * notmuch_thread_destroy (thread); +- * } +- * +- * notmuch_query_destroy (query); +- * +- * Note: If you are finished with a thread before its containing +- * query, you can call notmuch_thread_destroy to clean up some memory +- * sooner (as in the above example). Otherwise, if your thread objects +- * are long-lived, then you don't need to call notmuch_thread_destroy +- * and all the memory will still be reclaimed when the query is +- * destroyed. +- * +- * Note that there's no explicit destructor needed for the +- * notmuch_threads_t object. (For consistency, we do provide a +- * notmuch_threads_destroy function, but there's no good reason +- * to call it if the query is about to be destroyed). +- * +- * If a Xapian exception occurs this function will return NULL. +- */ ++// Execute a query for threads, returning a notmuch_threads_t object ++// which can be used to iterate over the results. The returned threads ++// object is owned by the query and as such, will only be valid until ++// notmuch_query_destroy. ++// ++// Typical usage might be: ++// ++// notmuch_query_t *query; ++// notmuch_threads_t *threads; ++// notmuch_thread_t *thread; ++// ++// query = notmuch_query_create (database, query_string); ++// ++// for (threads = notmuch_query_search_threads (query); ++// notmuch_threads_valid (threads); ++// notmuch_threads_move_to_next (threads)) ++// { ++// thread = notmuch_threads_get (threads); ++// .... ++// notmuch_thread_destroy (thread); ++// } ++// ++// notmuch_query_destroy (query); ++// ++// Note: If you are finished with a thread before its containing ++// query, you can call notmuch_thread_destroy to clean up some memory ++// sooner (as in the above example). Otherwise, if your thread objects ++// are long-lived, then you don't need to call notmuch_thread_destroy ++// and all the memory will still be reclaimed when the query is ++// destroyed. ++// ++// Note that there's no explicit destructor needed for the ++// notmuch_threads_t object. (For consistency, we do provide a ++// notmuch_threads_destroy function, but there's no good reason ++// to call it if the query is about to be destroyed). ++// ++// If a Xapian exception occurs this function will return NULL. + func (self *Query) SearchThreads() *Threads { + threads := C.notmuch_query_search_threads(self.query) + if threads == nil { +@@ -462,44 +453,43 @@ func (self *Query) SearchThreads() *Threads { + return &Threads{threads: threads} + } + +-/* Execute a query for messages, returning a notmuch_messages_t object +- * which can be used to iterate over the results. The returned +- * messages object is owned by the query and as such, will only be +- * valid until notmuch_query_destroy. +- * +- * Typical usage might be: +- * +- * notmuch_query_t *query; +- * notmuch_messages_t *messages; +- * notmuch_message_t *message; +- * +- * query = notmuch_query_create (database, query_string); +- * +- * for (messages = notmuch_query_search_messages (query); +- * notmuch_messages_valid (messages); +- * notmuch_messages_move_to_next (messages)) +- * { +- * message = notmuch_messages_get (messages); +- * .... +- * notmuch_message_destroy (message); +- * } +- * +- * notmuch_query_destroy (query); +- * +- * Note: If you are finished with a message before its containing +- * query, you can call notmuch_message_destroy to clean up some memory +- * sooner (as in the above example). Otherwise, if your message +- * objects are long-lived, then you don't need to call +- * notmuch_message_destroy and all the memory will still be reclaimed +- * when the query is destroyed. +- * +- * Note that there's no explicit destructor needed for the +- * notmuch_messages_t object. (For consistency, we do provide a +- * notmuch_messages_destroy function, but there's no good +- * reason to call it if the query is about to be destroyed). +- * +- * If a Xapian exception occurs this function will return NULL. +- */ ++// Execute a query for messages, returning a notmuch_messages_t object ++// which can be used to iterate over the results. The returned ++// messages object is owned by the query and as such, will only be ++// valid until notmuch_query_destroy. ++// ++// Typical usage might be: ++// ++// notmuch_query_t *query; ++// notmuch_messages_t *messages; ++// notmuch_message_t *message; ++// ++// query = notmuch_query_create (database, query_string); ++// ++// for (messages = notmuch_query_search_messages (query); ++// notmuch_messages_valid (messages); ++// notmuch_messages_move_to_next (messages)) ++// { ++// message = notmuch_messages_get (messages); ++// .... ++// notmuch_message_destroy (message); ++// } ++// ++// notmuch_query_destroy (query); ++// ++// Note: If you are finished with a message before its containing ++// query, you can call notmuch_message_destroy to clean up some memory ++// sooner (as in the above example). Otherwise, if your message ++// objects are long-lived, then you don't need to call ++// notmuch_message_destroy and all the memory will still be reclaimed ++// when the query is destroyed. ++// ++// Note that there's no explicit destructor needed for the ++// notmuch_messages_t object. (For consistency, we do provide a ++// notmuch_messages_destroy function, but there's no good ++// reason to call it if the query is about to be destroyed). ++// ++// If a Xapian exception occurs this function will return NULL. + func (self *Query) SearchMessages() *Messages { + msgs := C.notmuch_query_search_messages(self.query) + if msgs == nil { +@@ -508,41 +498,38 @@ func (self *Query) SearchMessages() *Messages { + return &Messages{messages: msgs} + } + +-/* Destroy a notmuch_query_t along with any associated resources. +- * +- * This will in turn destroy any notmuch_threads_t and +- * notmuch_messages_t objects generated by this query, (and in +- * turn any notmuch_thread_t and notmuch_message_t objects generated +- * from those results, etc.), if such objects haven't already been +- * destroyed. +- */ ++// Destroy a notmuch_query_t along with any associated resources. ++// ++// This will in turn destroy any notmuch_threads_t and ++// notmuch_messages_t objects generated by this query, (and in ++// turn any notmuch_thread_t and notmuch_message_t objects generated ++// from those results, etc.), if such objects haven't already been ++// destroyed. + func (self *Query) Destroy() { + if self.query != nil { + C.notmuch_query_destroy(self.query) + } + } + +-/* Return an estimate of the number of messages matching a search +- * +- * This function performs a search and returns Xapian's best +- * guess as to number of matching messages. +- * +- * If a Xapian exception occurs, this function may return 0 (after +- * printing a message). +- */ ++// Return an estimate of the number of messages matching a search ++// ++// This function performs a search and returns Xapian's best ++// guess as to number of matching messages. ++// ++// If a Xapian exception occurs, this function may return 0 (after ++// printing a message). + func (self *Query) CountMessages() uint { + return uint(C.notmuch_query_count_messages(self.query)) + } + +-/* Is the given 'threads' iterator pointing at a valid thread. +- * +- * When this function returns TRUE, notmuch_threads_get will return a +- * valid object. Whereas when this function returns FALSE, +- * notmuch_threads_get will return NULL. +- * +- * See the documentation of notmuch_query_search_threads for example +- * code showing how to iterate over a notmuch_threads_t object. +- */ ++// Is the given 'threads' iterator pointing at a valid thread. ++// ++// When this function returns TRUE, notmuch_threads_get will return a ++// valid object. Whereas when this function returns FALSE, ++// notmuch_threads_get will return NULL. ++// ++// See the documentation of notmuch_query_search_threads for example ++// code showing how to iterate over a notmuch_threads_t object. + func (self *Threads) Valid() bool { + if self.threads == nil { + return false +@@ -554,17 +541,16 @@ func (self *Threads) Valid() bool { + return true + } + +-/* Get the current thread from 'threads' as a notmuch_thread_t. +- * +- * Note: The returned thread belongs to 'threads' and has a lifetime +- * identical to it (and the query to which it belongs). +- * +- * See the documentation of notmuch_query_search_threads for example +- * code showing how to iterate over a notmuch_threads_t object. +- * +- * If an out-of-memory situation occurs, this function will return +- * NULL. +- */ ++// Get the current thread from 'threads' as a notmuch_thread_t. ++// ++// Note: The returned thread belongs to 'threads' and has a lifetime ++// identical to it (and the query to which it belongs). ++// ++// See the documentation of notmuch_query_search_threads for example ++// code showing how to iterate over a notmuch_threads_t object. ++// ++// If an out-of-memory situation occurs, this function will return ++// NULL. + func (self *Threads) Get() *Thread { + if self.threads == nil { + return nil +@@ -576,16 +562,15 @@ func (self *Threads) Get() *Thread { + return &Thread{thread} + } + +-/* Move the 'threads' iterator to the next thread. +- * +- * If 'threads' is already pointing at the last thread then the +- * iterator will be moved to a point just beyond that last thread, +- * (where notmuch_threads_valid will return FALSE and +- * notmuch_threads_get will return NULL). +- * +- * See the documentation of notmuch_query_search_threads for example +- * code showing how to iterate over a notmuch_threads_t object. +- */ ++// Move the 'threads' iterator to the next thread. ++// ++// If 'threads' is already pointing at the last thread then the ++// iterator will be moved to a point just beyond that last thread, ++// (where notmuch_threads_valid will return FALSE and ++// notmuch_threads_get will return NULL). ++// ++// See the documentation of notmuch_query_search_threads for example ++// code showing how to iterate over a notmuch_threads_t object. + func (self *Threads) MoveToNext() { + if self.threads == nil { + return +@@ -593,26 +578,23 @@ func (self *Threads) MoveToNext() { + C.notmuch_threads_move_to_next(self.threads) + } + +-/* Destroy a notmuch_threads_t object. +- * +- * It's not strictly necessary to call this function. All memory from +- * the notmuch_threads_t object will be reclaimed when the +- * containg query object is destroyed. +- */ ++// Destroy a notmuch_threads_t object. ++// ++// It's not strictly necessary to call this function. All memory from ++// the notmuch_threads_t object will be reclaimed when the ++// containg query object is destroyed. + func (self *Threads) Destroy() { + if self.threads != nil { + C.notmuch_threads_destroy(self.threads) + } + } + +-/** +- * Get the thread ID of 'thread'. +- * +- * The returned string belongs to 'thread' and as such, should not be +- * modified by the caller and will only be valid for as long as the +- * thread is valid, (which is until notmuch_thread_destroy or until +- * the query from which it derived is destroyed). +- */ ++// Get the thread ID of 'thread'. ++// ++// The returned string belongs to 'thread' and as such, should not be ++// modified by the caller and will only be valid for as long as the ++// thread is valid, (which is until notmuch_thread_destroy or until ++// the query from which it derived is destroyed). + func (self *Thread) GetThreadId() string { + if self.thread == nil { + return "" +@@ -624,12 +606,10 @@ func (self *Thread) GetThreadId() string { + return C.GoString(id) + } + +-/** +- * Get the total number of messages in 'thread'. +- * +- * This count consists of all messages in the database belonging to +- * this thread. Contrast with notmuch_thread_get_matched_messages() . +- */ ++// Get the total number of messages in 'thread'. ++// ++// This count consists of all messages in the database belonging to ++// this thread. Contrast with notmuch_thread_get_matched_messages() . + func (self *Thread) GetTotalMessages() int { + if self.thread == nil { + return 0 +@@ -637,16 +617,14 @@ func (self *Thread) GetTotalMessages() int { + return int(C.notmuch_thread_get_total_messages(self.thread)) + } + +-/** +- * Get a notmuch_messages_t iterator for the top-level messages in +- * 'thread' in oldest-first order. +- * +- * This iterator will not necessarily iterate over all of the messages +- * in the thread. It will only iterate over the messages in the thread +- * which are not replies to other messages in the thread. +- * +- * The returned list will be destroyed when the thread is destroyed. +- */ ++// Get a notmuch_messages_t iterator for the top-level messages in ++// 'thread' in oldest-first order. ++// ++// This iterator will not necessarily iterate over all of the messages ++// in the thread. It will only iterate over the messages in the thread ++// which are not replies to other messages in the thread. ++// ++// The returned list will be destroyed when the thread is destroyed. + func (self *Thread) GetToplevelMessages() (*Messages, Status) { + if self.thread == nil { + return nil, STATUS_NULL_POINTER +@@ -659,12 +637,10 @@ func (self *Thread) GetToplevelMessages() (*Messages, Status) { + return &Messages{msgs}, STATUS_SUCCESS + } + +-/** +- * Get a notmuch_thread_t iterator for all messages in 'thread' in +- * oldest-first order. +- * +- * The returned list will be destroyed when the thread is destroyed. +- */ ++// Get a notmuch_thread_t iterator for all messages in 'thread' in ++// oldest-first order. ++// ++// The returned list will be destroyed when the thread is destroyed. + func (self *Thread) GetMessages() (*Messages, Status) { + if self.thread == nil { + return nil, STATUS_NULL_POINTER +@@ -677,15 +653,13 @@ func (self *Thread) GetMessages() (*Messages, Status) { + return &Messages{msgs}, STATUS_SUCCESS + } + +-/** +- * Get the number of messages in 'thread' that matched the search. +- * +- * This count includes only the messages in this thread that were +- * matched by the search from which the thread was created and were +- * not excluded by any exclude tags passed in with the query (see +- * notmuch_query_add_tag_exclude). Contrast with +- * notmuch_thread_get_total_messages() . +- */ ++// Get the number of messages in 'thread' that matched the search. ++// ++// This count includes only the messages in this thread that were ++// matched by the search from which the thread was created and were ++// not excluded by any exclude tags passed in with the query (see ++// notmuch_query_add_tag_exclude). Contrast with ++// notmuch_thread_get_total_messages(). + func (self *Thread) GetMatchedMessages() int { + if self.thread == nil { + return 0 +@@ -693,22 +667,20 @@ func (self *Thread) GetMatchedMessages() int { + return int(C.notmuch_thread_get_matched_messages(self.thread)) + } + +-/** +- * Get the authors of 'thread' as a UTF-8 string. +- * +- * The returned string is a comma-separated list of the names of the +- * authors of mail messages in the query results that belong to this +- * thread. +- * +- * The string contains authors of messages matching the query first, then +- * non-matched authors (with the two groups separated by '|'). Within +- * each group, authors are ordered by date. +- * +- * The returned string belongs to 'thread' and as such, should not be +- * modified by the caller and will only be valid for as long as the +- * thread is valid, (which is until notmuch_thread_destroy or until +- * the query from which it derived is destroyed). +- */ ++// Get the authors of 'thread' as a UTF-8 string. ++// ++// The returned string is a comma-separated list of the names of the ++// authors of mail messages in the query results that belong to this ++// thread. ++// ++// The string contains authors of messages matching the query first, then ++// non-matched authors (with the two groups separated by '|'). Within ++// each group, authors are ordered by date. ++// ++// The returned string belongs to 'thread' and as such, should not be ++// modified by the caller and will only be valid for as long as the ++// thread is valid, (which is until notmuch_thread_destroy or until ++// the query from which it derived is destroyed). + func (self *Thread) GetAuthors() string { + if self.thread == nil { + return "" +@@ -720,18 +692,16 @@ func (self *Thread) GetAuthors() string { + return C.GoString(str) + } + +-/** +- * Get the subject of 'thread' as a UTF-8 string. +- * +- * The subject is taken from the first message (according to the query +- * order---see notmuch_query_set_sort) in the query results that +- * belongs to this thread. +- * +- * The returned string belongs to 'thread' and as such, should not be +- * modified by the caller and will only be valid for as long as the +- * thread is valid, (which is until notmuch_thread_destroy or until +- * the query from which it derived is destroyed). +- */ ++// Get the subject of 'thread' as a UTF-8 string. ++// ++// The subject is taken from the first message (according to the query ++// order---see notmuch_query_set_sort) in the query results that ++// belongs to this thread. ++// ++// The returned string belongs to 'thread' and as such, should not be ++// modified by the caller and will only be valid for as long as the ++// thread is valid, (which is until notmuch_thread_destroy or until ++// the query from which it derived is destroyed). + func (self *Thread) GetSubject() string { + if self.thread == nil { + return "" +@@ -743,9 +713,7 @@ func (self *Thread) GetSubject() string { + return C.GoString(str) + } + +-/** +- * Get the date of the oldest message in 'thread' as a time_t value. +- */ ++// Get the date of the oldest message in 'thread' as a time_t value. + func (self *Thread) GetOldestDate() int64 { + if self.thread == nil { + return 0 +@@ -755,9 +723,7 @@ func (self *Thread) GetOldestDate() int64 { + return int64(date) + } + +-/** +- * Get the date of the newest message in 'thread' as a time_t value. +- */ ++// Get the date of the newest message in 'thread' as a time_t value. + func (self *Thread) GetNewestDate() int64 { + if self.thread == nil { + return 0 +@@ -767,43 +733,41 @@ func (self *Thread) GetNewestDate() int64 { + return int64(date) + } + +-/** +- * Get the tags for 'thread', returning a notmuch_tags_t object which +- * can be used to iterate over all tags. +- * +- * Note: In the Notmuch database, tags are stored on individual +- * messages, not on threads. So the tags returned here will be all +- * tags of the messages which matched the search and which belong to +- * this thread. +- * +- * The tags object is owned by the thread and as such, will only be +- * valid for as long as the thread is valid, (for example, until +- * notmuch_thread_destroy or until the query from which it derived is +- * destroyed). +- * +- * Typical usage might be: +- * +- * notmuch_thread_t *thread; +- * notmuch_tags_t *tags; +- * const char *tag; +- * +- * thread = notmuch_threads_get (threads); +- * +- * for (tags = notmuch_thread_get_tags (thread); +- * notmuch_tags_valid (tags); +- * notmuch_tags_move_to_next (tags)) +- * { +- * tag = notmuch_tags_get (tags); +- * .... +- * } +- * +- * notmuch_thread_destroy (thread); +- * +- * Note that there's no explicit destructor needed for the +- * notmuch_tags_t object. (For consistency, we do provide a +- * notmuch_tags_destroy function, but there's no good reason to call +- * it if the message is about to be destroyed). +- */ ++// Get the tags for 'thread', returning a notmuch_tags_t object which ++// can be used to iterate over all tags. ++// ++// Note: In the Notmuch database, tags are stored on individual ++// messages, not on threads. So the tags returned here will be all ++// tags of the messages which matched the search and which belong to ++// this thread. ++// ++// The tags object is owned by the thread and as such, will only be ++// valid for as long as the thread is valid, (for example, until ++// notmuch_thread_destroy or until the query from which it derived is ++// destroyed). ++// ++// Typical usage might be: ++// ++// notmuch_thread_t *thread; ++// notmuch_tags_t *tags; ++// const char *tag; ++// ++// thread = notmuch_threads_get (threads); ++// ++// for (tags = notmuch_thread_get_tags (thread); ++// notmuch_tags_valid (tags); ++// notmuch_tags_move_to_next (tags)) ++// { ++// tag = notmuch_tags_get (tags); ++// .... ++// } ++// ++// notmuch_thread_destroy (thread); ++// ++// Note that there's no explicit destructor needed for the ++// notmuch_tags_t object. (For consistency, we do provide a ++// notmuch_tags_destroy function, but there's no good reason to call ++// it if the message is about to be destroyed). + func (self *Thread) GetTags() *Tags { + if self.thread == nil { + return nil +@@ -817,24 +781,21 @@ func (self *Thread) GetTags() *Tags { + return &Tags{tags} + } + +-/** +- * Destroy a notmuch_thread_t object. +- */ ++// Destroy a notmuch_thread_t object. + func (self *Thread) Destroy() { + if self.thread != nil { + C.notmuch_thread_destroy(self.thread) + } + } + +-/* Is the given 'messages' iterator pointing at a valid message. +- * +- * When this function returns TRUE, notmuch_messages_get will return a +- * valid object. Whereas when this function returns FALSE, +- * notmuch_messages_get will return NULL. +- * +- * See the documentation of notmuch_query_search_messages for example +- * code showing how to iterate over a notmuch_messages_t object. +- */ ++// Is the given 'messages' iterator pointing at a valid message. ++// ++// When this function returns TRUE, notmuch_messages_get will return a ++// valid object. Whereas when this function returns FALSE, ++// notmuch_messages_get will return NULL. ++// ++// See the documentation of notmuch_query_search_messages for example ++// code showing how to iterate over a notmuch_messages_t object. + func (self *Messages) Valid() bool { + if self.messages == nil { + return false +@@ -846,17 +807,16 @@ func (self *Messages) Valid() bool { + return true + } + +-/* Get the current message from 'messages' as a notmuch_message_t. +- * +- * Note: The returned message belongs to 'messages' and has a lifetime +- * identical to it (and the query to which it belongs). +- * +- * See the documentation of notmuch_query_search_messages for example +- * code showing how to iterate over a notmuch_messages_t object. +- * +- * If an out-of-memory situation occurs, this function will return +- * NULL. +- */ ++// Get the current message from 'messages' as a notmuch_message_t. ++// ++// Note: The returned message belongs to 'messages' and has a lifetime ++// identical to it (and the query to which it belongs). ++// ++// See the documentation of notmuch_query_search_messages for example ++// code showing how to iterate over a notmuch_messages_t object. ++// ++// If an out-of-memory situation occurs, this function will return ++// NULL. + func (self *Messages) Get() *Message { + if self.messages == nil { + return nil +@@ -868,16 +828,15 @@ func (self *Messages) Get() *Message { + return &Message{message: msg} + } + +-/* Move the 'messages' iterator to the next message. +- * +- * If 'messages' is already pointing at the last message then the +- * iterator will be moved to a point just beyond that last message, +- * (where notmuch_messages_valid will return FALSE and +- * notmuch_messages_get will return NULL). +- * +- * See the documentation of notmuch_query_search_messages for example +- * code showing how to iterate over a notmuch_messages_t object. +- */ ++// Move the 'messages' iterator to the next message. ++// ++// If 'messages' is already pointing at the last message then the ++// iterator will be moved to a point just beyond that last message, ++// (where notmuch_messages_valid will return FALSE and ++// notmuch_messages_get will return NULL). ++// ++// See the documentation of notmuch_query_search_messages for example ++// code showing how to iterate over a notmuch_messages_t object. + func (self *Messages) MoveToNext() { + if self.messages == nil { + return +@@ -885,30 +844,28 @@ func (self *Messages) MoveToNext() { + C.notmuch_messages_move_to_next(self.messages) + } + +-/* Destroy a notmuch_messages_t object. +- * +- * It's not strictly necessary to call this function. All memory from +- * the notmuch_messages_t object will be reclaimed when the containing +- * query object is destroyed. +- */ ++// Destroy a notmuch_messages_t object. ++// ++// It's not strictly necessary to call this function. All memory from ++// the notmuch_messages_t object will be reclaimed when the containing ++// query object is destroyed. + func (self *Messages) Destroy() { + if self.messages != nil { + C.notmuch_messages_destroy(self.messages) + } + } + +-/* Return a list of tags from all messages. +- * +- * The resulting list is guaranteed not to contain duplicated tags. +- * +- * WARNING: You can no longer iterate over messages after calling this +- * function, because the iterator will point at the end of the list. +- * We do not have a function to reset the iterator yet and the only +- * way how you can iterate over the list again is to recreate the +- * message list. +- * +- * The function returns NULL on error. +- */ ++// Return a list of tags from all messages. ++// ++// The resulting list is guaranteed not to contain duplicated tags. ++// ++// WARNING: You can no longer iterate over messages after calling this ++// function, because the iterator will point at the end of the list. ++// We do not have a function to reset the iterator yet and the only ++// way how you can iterate over the list again is to recreate the ++// message list. ++// ++// The function returns NULL on error. + func (self *Messages) CollectTags() *Tags { + if self.messages == nil { + return nil +@@ -920,17 +877,16 @@ func (self *Messages) CollectTags() *Tags { + return &Tags{tags: tags} + } + +-/* Get the message ID of 'message'. +- * +- * The returned string belongs to 'message' and as such, should not be +- * modified by the caller and will only be valid for as long as the +- * message is valid, (which is until the query from which it derived +- * is destroyed). +- * +- * This function will not return NULL since Notmuch ensures that every +- * message has a unique message ID, (Notmuch will generate an ID for a +- * message if the original file does not contain one). +- */ ++// Get the message ID of 'message'. ++// ++// The returned string belongs to 'message' and as such, should not be ++// modified by the caller and will only be valid for as long as the ++// message is valid, (which is until the query from which it derived ++// is destroyed). ++// ++// This function will not return NULL since Notmuch ensures that every ++// message has a unique message ID, (Notmuch will generate an ID for a ++// message if the original file does not contain one). + func (self *Message) GetMessageId() string { + + if self.message == nil { +@@ -945,17 +901,16 @@ func (self *Message) GetMessageId() string { + return C.GoString(id) + } + +-/* Get the thread ID of 'message'. +- * +- * The returned string belongs to 'message' and as such, should not be +- * modified by the caller and will only be valid for as long as the +- * message is valid, (for example, until the user calls +- * notmuch_message_destroy on 'message' or until a query from which it +- * derived is destroyed). +- * +- * This function will not return NULL since Notmuch ensures that every +- * message belongs to a single thread. +- */ ++// Get the thread ID of 'message'. ++// ++// The returned string belongs to 'message' and as such, should not be ++// modified by the caller and will only be valid for as long as the ++// message is valid, (for example, until the user calls ++// notmuch_message_destroy on 'message' or until a query from which it ++// derived is destroyed). ++// ++// This function will not return NULL since Notmuch ensures that every ++// message belongs to a single thread. + func (self *Message) GetThreadId() string { + + if self.message == nil { +@@ -972,23 +927,22 @@ func (self *Message) GetThreadId() string { + return C.GoString(id) + } + +-/* Get a notmuch_messages_t iterator for all of the replies to +- * 'message'. +- * +- * Note: This call only makes sense if 'message' was ultimately +- * obtained from a notmuch_thread_t object, (such as by coming +- * directly from the result of calling notmuch_thread_get_ +- * toplevel_messages or by any number of subsequent +- * calls to notmuch_message_get_replies). +- * +- * If 'message' was obtained through some non-thread means, (such as +- * by a call to notmuch_query_search_messages), then this function +- * will return NULL. +- * +- * If there are no replies to 'message', this function will return +- * NULL. (Note that notmuch_messages_valid will accept that NULL +- * value as legitimate, and simply return FALSE for it.) +- */ ++// Get a notmuch_messages_t iterator for all of the replies to ++// 'message'. ++// ++// Note: This call only makes sense if 'message' was ultimately ++// obtained from a notmuch_thread_t object, (such as by coming ++// directly from the result of calling notmuch_thread_get_ ++// toplevel_messages or by any number of subsequent ++// calls to notmuch_message_get_replies). ++// ++// If 'message' was obtained through some non-thread means, (such as ++// by a call to notmuch_query_search_messages), then this function ++// will return NULL. ++// ++// If there are no replies to 'message', this function will return ++// NULL. (Note that notmuch_messages_valid will accept that NULL ++// value as legitimate, and simply return FALSE for it.) + func (self *Message) GetReplies() *Messages { + if self.message == nil { + return nil +@@ -1000,20 +954,19 @@ func (self *Message) GetReplies() *Messages { + return &Messages{messages: msgs} + } + +-/* Get a filename for the email corresponding to 'message'. +- * +- * The returned filename is an absolute filename, (the initial +- * component will match notmuch_database_get_path() ). +- * +- * The returned string belongs to the message so should not be +- * modified or freed by the caller (nor should it be referenced after +- * the message is destroyed). +- * +- * Note: If this message corresponds to multiple files in the mail +- * store, (that is, multiple files contain identical message IDs), +- * this function will arbitrarily return a single one of those +- * filenames. +- */ ++// Get a filename for the email corresponding to 'message'. ++// ++// The returned filename is an absolute filename, (the initial ++// component will match notmuch_database_get_path() ). ++// ++// The returned string belongs to the message so should not be ++// modified or freed by the caller (nor should it be referenced after ++// the message is destroyed). ++// ++// Note: If this message corresponds to multiple files in the mail ++// store, (that is, multiple files contain identical message IDs), ++// this function will arbitrarily return a single one of those ++// filenames. + func (self *Message) GetFileName() string { + if self.message == nil { + return "" +@@ -1035,7 +988,7 @@ const ( + MESSAGE_FLAG_MATCH Flag = 0 + ) + +-/* Get a value of a flag for the email corresponding to 'message'. */ ++// Get a value of a flag for the email corresponding to 'message'. + func (self *Message) GetFlag(flag Flag) bool { + if self.message == nil { + return false +@@ -1047,7 +1000,7 @@ func (self *Message) GetFlag(flag Flag) bool { + return true + } + +-/* Set a value of a flag for the email corresponding to 'message'. */ ++// Set a value of a flag for the email corresponding to 'message'. + func (self *Message) SetFlag(flag Flag, value bool) { + if self.message == nil { + return +@@ -1059,15 +1012,14 @@ func (self *Message) SetFlag(flag Flag, value bool) { + C.notmuch_message_set_flag(self.message, C.notmuch_message_flag_t(flag), v) + } + +-/* Get the timestamp (seconds since the epoch) of 'message'. +- * +- * Return status: +- * +- * NOTMUCH_STATUS_SUCCESS: Timestamp successfully retrieved +- * +- * NOTMUCH_STATUS_NULL_POINTER: The 'message' argument is NULL +- * +- */ ++// Get the timestamp (seconds since the epoch) of 'message'. ++// ++// Return status: ++// ++// NOTMUCH_STATUS_SUCCESS: Timestamp successfully retrieved ++// ++// NOTMUCH_STATUS_NULL_POINTER: The 'message' argument is NULL ++// + func (self *Message) GetDate() (int64, Status) { + if self.message == nil { + return -1, STATUS_NULL_POINTER +@@ -1076,18 +1028,17 @@ func (self *Message) GetDate() (int64, Status) { + return int64(timestamp), STATUS_SUCCESS + } + +-/* Get the value of the specified header from 'message'. +- * +- * The value will be read from the actual message file, not from the +- * notmuch database. The header name is case insensitive. +- * +- * The returned string belongs to the message so should not be +- * modified or freed by the caller (nor should it be referenced after +- * the message is destroyed). +- * +- * Returns an empty string ("") if the message does not contain a +- * header line matching 'header'. Returns NULL if any error occurs. +- */ ++// Get the value of the specified header from 'message'. ++// ++// The value will be read from the actual message file, not from the ++// notmuch database. The header name is case insensitive. ++// ++// The returned string belongs to the message so should not be ++// modified or freed by the caller (nor should it be referenced after ++// the message is destroyed). ++// ++// Returns an empty string ("") if the message does not contain a ++// header line matching 'header'. Returns NULL if any error occurs. + func (self *Message) GetHeader(header string) string { + if self.message == nil { + return "" +@@ -1105,36 +1056,35 @@ func (self *Message) GetHeader(header string) string { + return C.GoString(value) + } + +-/* Get the tags for 'message', returning a notmuch_tags_t object which +- * can be used to iterate over all tags. +- * +- * The tags object is owned by the message and as such, will only be +- * valid for as long as the message is valid, (which is until the +- * query from which it derived is destroyed). +- * +- * Typical usage might be: +- * +- * notmuch_message_t *message; +- * notmuch_tags_t *tags; +- * const char *tag; +- * +- * message = notmuch_database_find_message (database, message_id); +- * +- * for (tags = notmuch_message_get_tags (message); +- * notmuch_tags_valid (tags); +- * notmuch_result_move_to_next (tags)) +- * { +- * tag = notmuch_tags_get (tags); +- * .... +- * } +- * +- * notmuch_message_destroy (message); +- * +- * Note that there's no explicit destructor needed for the +- * notmuch_tags_t object. (For consistency, we do provide a +- * notmuch_tags_destroy function, but there's no good reason to call +- * it if the message is about to be destroyed). +- */ ++// Get the tags for 'message', returning a notmuch_tags_t object which ++// can be used to iterate over all tags. ++// ++// The tags object is owned by the message and as such, will only be ++// valid for as long as the message is valid, (which is until the ++// query from which it derived is destroyed). ++// ++// Typical usage might be: ++// ++// notmuch_message_t *message; ++// notmuch_tags_t *tags; ++// const char *tag; ++// ++// message = notmuch_database_find_message (database, message_id); ++// ++// for (tags = notmuch_message_get_tags (message); ++// notmuch_tags_valid (tags); ++// notmuch_result_move_to_next (tags)) ++// { ++// tag = notmuch_tags_get (tags); ++// .... ++// } ++// ++// notmuch_message_destroy (message); ++// ++// Note that there's no explicit destructor needed for the ++// notmuch_tags_t object. (For consistency, we do provide a ++// notmuch_tags_destroy function, but there's no good reason to call ++// it if the message is about to be destroyed). + func (self *Message) GetTags() *Tags { + if self.message == nil { + return nil +@@ -1146,23 +1096,22 @@ func (self *Message) GetTags() *Tags { + return &Tags{tags: tags} + } + +-/* The longest possible tag value. */ ++// The longest possible tag value. + const TAG_MAX = 200 + +-/* Add a tag to the given message. +- * +- * Return value: +- * +- * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message +- * +- * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL +- * +- * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long +- * (exceeds NOTMUCH_TAG_MAX) +- * +- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only +- * mode so message cannot be modified. +- */ ++// Add a tag to the given message. ++// ++// Return value: ++// ++// NOTMUCH_STATUS_SUCCESS: Tag successfully added to message ++// ++// NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL ++// ++// NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long ++// (exceeds NOTMUCH_TAG_MAX) ++// ++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only ++// mode so message cannot be modified. + func (self *Message) AddTag(tag string) Status { + if self.message == nil { + return STATUS_NULL_POINTER +@@ -1173,20 +1122,19 @@ func (self *Message) AddTag(tag string) Status { + return Status(C.notmuch_message_add_tag(self.message, c_tag)) + } + +-/* Remove a tag from the given message. +- * +- * Return value: +- * +- * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message +- * +- * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL +- * +- * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long +- * (exceeds NOTMUCH_TAG_MAX) +- * +- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only +- * mode so message cannot be modified. +- */ ++// Remove a tag from the given message. ++// ++// Return value: ++// ++// NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message ++// ++// NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL ++// ++// NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long ++// (exceeds NOTMUCH_TAG_MAX) ++// ++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only ++// mode so message cannot be modified. + func (self *Message) RemoveTag(tag string) Status { + if self.message == nil { + return STATUS_NULL_POINTER +@@ -1197,14 +1145,13 @@ func (self *Message) RemoveTag(tag string) Status { + return Status(C.notmuch_message_remove_tag(self.message, c_tag)) + } + +-/* Remove all tags from the given message. +- * +- * See notmuch_message_freeze for an example showing how to safely +- * replace tag values. +- * +- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only +- * mode so message cannot be modified. +- */ ++// Remove all tags from the given message. ++// ++// See notmuch_message_freeze for an example showing how to safely ++// replace tag values. ++// ++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only ++// mode so message cannot be modified. + func (self *Message) RemoveAllTags() Status { + if self.message == nil { + return STATUS_NULL_POINTER +@@ -1212,46 +1159,45 @@ func (self *Message) RemoveAllTags() Status { + return Status(C.notmuch_message_remove_all_tags(self.message)) + } + +-/* Freeze the current state of 'message' within the database. +- * +- * This means that changes to the message state, (via +- * notmuch_message_add_tag, notmuch_message_remove_tag, and +- * notmuch_message_remove_all_tags), will not be committed to the +- * database until the message is thawed with notmuch_message_thaw. +- * +- * Multiple calls to freeze/thaw are valid and these calls will +- * "stack". That is there must be as many calls to thaw as to freeze +- * before a message is actually thawed. +- * +- * The ability to do freeze/thaw allows for safe transactions to +- * change tag values. For example, explicitly setting a message to +- * have a given set of tags might look like this: +- * +- * notmuch_message_freeze (message); +- * +- * notmuch_message_remove_all_tags (message); +- * +- * for (i = 0; i < NUM_TAGS; i++) +- * notmuch_message_add_tag (message, tags[i]); +- * +- * notmuch_message_thaw (message); +- * +- * With freeze/thaw used like this, the message in the database is +- * guaranteed to have either the full set of original tag values, or +- * the full set of new tag values, but nothing in between. +- * +- * Imagine the example above without freeze/thaw and the operation +- * somehow getting interrupted. This could result in the message being +- * left with no tags if the interruption happened after +- * notmuch_message_remove_all_tags but before notmuch_message_add_tag. +- * +- * Return value: +- * +- * NOTMUCH_STATUS_SUCCESS: Message successfully frozen. +- * +- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only +- * mode so message cannot be modified. +- */ ++// Freeze the current state of 'message' within the database. ++// ++// This means that changes to the message state, (via ++// notmuch_message_add_tag, notmuch_message_remove_tag, and ++// notmuch_message_remove_all_tags), will not be committed to the ++// database until the message is thawed with notmuch_message_thaw. ++// ++// Multiple calls to freeze/thaw are valid and these calls will ++// "stack". That is there must be as many calls to thaw as to freeze ++// before a message is actually thawed. ++// ++// The ability to do freeze/thaw allows for safe transactions to ++// change tag values. For example, explicitly setting a message to ++// have a given set of tags might look like this: ++// ++// notmuch_message_freeze (message); ++// ++// notmuch_message_remove_all_tags (message); ++// ++// for (i = 0; i < NUM_TAGS; i++) ++// notmuch_message_add_tag (message, tags[i]); ++// ++// notmuch_message_thaw (message); ++// ++// With freeze/thaw used like this, the message in the database is ++// guaranteed to have either the full set of original tag values, or ++// the full set of new tag values, but nothing in between. ++// ++// Imagine the example above without freeze/thaw and the operation ++// somehow getting interrupted. This could result in the message being ++// left with no tags if the interruption happened after ++// notmuch_message_remove_all_tags but before notmuch_message_add_tag. ++// ++// Return value: ++// ++// NOTMUCH_STATUS_SUCCESS: Message successfully frozen. ++// ++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only ++// mode so message cannot be modified. + func (self *Message) Freeze() Status { + if self.message == nil { + return STATUS_NULL_POINTER +@@ -1259,26 +1205,25 @@ func (self *Message) Freeze() Status { + return Status(C.notmuch_message_freeze(self.message)) + } + +-/* Thaw the current 'message', synchronizing any changes that may have +- * occurred while 'message' was frozen into the notmuch database. +- * +- * See notmuch_message_freeze for an example of how to use this +- * function to safely provide tag changes. +- * +- * Multiple calls to freeze/thaw are valid and these calls with +- * "stack". That is there must be as many calls to thaw as to freeze +- * before a message is actually thawed. +- * +- * Return value: +- * +- * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least +- * its frozen count has successfully been reduced by 1). +- * +- * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw +- * an unfrozen message. That is, there have been an unbalanced +- * number of calls to notmuch_message_freeze and +- * notmuch_message_thaw. +- */ ++// Thaw the current 'message', synchronizing any changes that may have ++// occurred while 'message' was frozen into the notmuch database. ++// ++// See notmuch_message_freeze for an example of how to use this ++// function to safely provide tag changes. ++// ++// Multiple calls to freeze/thaw are valid and these calls with ++// "stack". That is there must be as many calls to thaw as to freeze ++// before a message is actually thawed. ++// ++// Return value: ++// ++// NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least ++// its frozen count has successfully been reduced by 1). ++// ++// NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw ++// an unfrozen message. That is, there have been an unbalanced ++// number of calls to notmuch_message_freeze and ++// notmuch_message_thaw. + func (self *Message) Thaw() Status { + if self.message == nil { + return STATUS_NULL_POINTER +@@ -1287,14 +1232,13 @@ func (self *Message) Thaw() Status { + return Status(C.notmuch_message_thaw(self.message)) + } + +-/* Destroy a notmuch_message_t object. +- * +- * It can be useful to call this function in the case of a single +- * query object with many messages in the result, (such as iterating +- * over the entire database). Otherwise, it's fine to never call this +- * function and there will still be no memory leaks. (The memory from +- * the messages get reclaimed when the containing query is destroyed.) +- */ ++// Destroy a notmuch_message_t object. ++// ++// It can be useful to call this function in the case of a single ++// query object with many messages in the result, (such as iterating ++// over the entire database). Otherwise, it's fine to never call this ++// function and there will still be no memory leaks. (The memory from ++// the messages get reclaimed when the containing query is destroyed.) + func (self *Message) Destroy() { + if self.message == nil { + return +@@ -1302,15 +1246,14 @@ func (self *Message) Destroy() { + C.notmuch_message_destroy(self.message) + } + +-/* Is the given 'tags' iterator pointing at a valid tag. +- * +- * When this function returns TRUE, notmuch_tags_get will return a +- * valid string. Whereas when this function returns FALSE, +- * notmuch_tags_get will return NULL. +- * +- * See the documentation of notmuch_message_get_tags for example code +- * showing how to iterate over a notmuch_tags_t object. +- */ ++// Is the given 'tags' iterator pointing at a valid tag. ++// ++// When this function returns TRUE, notmuch_tags_get will return a ++// valid string. Whereas when this function returns FALSE, ++// notmuch_tags_get will return NULL. ++// ++// See the documentation of notmuch_message_get_tags for example code ++// showing how to iterate over a notmuch_tags_t object. + func (self *Tags) Valid() bool { + if self.tags == nil { + return false +@@ -1322,14 +1265,13 @@ func (self *Tags) Valid() bool { + return true + } + +-/* Get the current tag from 'tags' as a string. +- * +- * Note: The returned string belongs to 'tags' and has a lifetime +- * identical to it (and the query to which it ultimately belongs). +- * +- * See the documentation of notmuch_message_get_tags for example code +- * showing how to iterate over a notmuch_tags_t object. +- */ ++// Get the current tag from 'tags' as a string. ++// ++// Note: The returned string belongs to 'tags' and has a lifetime ++// identical to it (and the query to which it ultimately belongs). ++// ++// See the documentation of notmuch_message_get_tags for example code ++// showing how to iterate over a notmuch_tags_t object. + func (self *Tags) Get() string { + if self.tags == nil { + return "" +@@ -1343,16 +1285,15 @@ func (self *Tags) String() string { + return self.Get() + } + +-/* Move the 'tags' iterator to the next tag. +- * +- * If 'tags' is already pointing at the last tag then the iterator +- * will be moved to a point just beyond that last tag, (where +- * notmuch_tags_valid will return FALSE and notmuch_tags_get will +- * return NULL). +- * +- * See the documentation of notmuch_message_get_tags for example code +- * showing how to iterate over a notmuch_tags_t object. +- */ ++// Move the 'tags' iterator to the next tag. ++// ++// If 'tags' is already pointing at the last tag then the iterator ++// will be moved to a point just beyond that last tag, (where ++// notmuch_tags_valid will return FALSE and notmuch_tags_get will ++// return NULL). ++// ++// See the documentation of notmuch_message_get_tags for example code ++// showing how to iterate over a notmuch_tags_t object. + func (self *Tags) MoveToNext() { + if self.tags == nil { + return +@@ -1360,12 +1301,11 @@ func (self *Tags) MoveToNext() { + C.notmuch_tags_move_to_next(self.tags) + } + +-/* Destroy a notmuch_tags_t object. +- * +- * It's not strictly necessary to call this function. All memory from +- * the notmuch_tags_t object will be reclaimed when the containing +- * message or query objects are destroyed. +- */ ++// Destroy a notmuch_tags_t object. ++// ++// It's not strictly necessary to call this function. All memory from ++// the notmuch_tags_t object will be reclaimed when the containing ++// message or query objects are destroyed. + func (self *Tags) Destroy() { + if self.tags == nil { + return +@@ -1375,7 +1315,7 @@ func (self *Tags) Destroy() { + + // TODO: wrap notmuch_directory_ + +-/* Destroy a notmuch_directory_t object. */ ++// Destroy a notmuch_directory_t object. + func (self *Directory) Destroy() { + if self.dir == nil { + return +@@ -1385,15 +1325,14 @@ func (self *Directory) Destroy() { + + // TODO: wrap notmuch_filenames_ + +-/* Destroy a notmuch_filenames_t object. +- * +- * It's not strictly necessary to call this function. All memory from +- * the notmuch_filenames_t object will be reclaimed when the +- * containing directory object is destroyed. +- * +- * It is acceptable to pass NULL for 'filenames', in which case this +- * function will do nothing. +- */ ++// Destroy a notmuch_filenames_t object. ++// ++// It's not strictly necessary to call this function. All memory from ++// the notmuch_filenames_t object will be reclaimed when the ++// containing directory object is destroyed. ++// ++// It is acceptable to pass NULL for 'filenames', in which case this ++// function will do nothing. + func (self *Filenames) Destroy() { + if self.fnames == nil { + return +@@ -1401,4 +1340,4 @@ func (self *Filenames) Destroy() { + C.notmuch_filenames_destroy(self.fnames) + } + +-/* EOF */ ++// EOF +-- +2.4.2 +