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 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