--- /dev/null
+Return-Path: <feh@noam.feh.name>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 34CC8431FBF\r
+ for <notmuch@notmuchmail.org>; Sat, 2 Mar 2013 06:57:37 -0800 (PST)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: 0\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]\r
+ autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id LVbPBZBrfe5w for <notmuch@notmuchmail.org>;\r
+ Sat, 2 Mar 2013 06:57:32 -0800 (PST)\r
+X-Greylist: delayed 375 seconds by postgrey-1.32 at olra;\r
+ Sat, 02 Mar 2013 06:57:27 PST\r
+Received: from noam.feh.name (noam.feh.name [176.9.34.52])\r
+ by olra.theworths.org (Postfix) with ESMTP id EE2C5431FAE\r
+ for <notmuch@notmuchmail.org>; Sat, 2 Mar 2013 06:57:27 -0800 (PST)\r
+Received: by noam.feh.name (Postfix, from userid 1000)\r
+ id 9C487157C123; Sat, 2 Mar 2013 15:51:11 +0100 (CET)\r
+From: Julius Plenz <julius@plenz.com>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH 1/3] Go bindings: clean up the documentation\r
+Date: Sat, 2 Mar 2013 15:50:54 +0100\r
+Message-Id: <1362235856-15358-1-git-send-email-julius@plenz.com>\r
+X-Mailer: git-send-email 1.7.2.5\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=UTF-8\r
+Content-Transfer-Encoding: 8bit\r
+X-Mailman-Approved-At: Sat, 02 Mar 2013 09:47:30 -0800\r
+Cc: Julius Plenz <julius@plenz.com>\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Sat, 02 Mar 2013 14:57:37 -0000\r
+\r
+Most of the copy&paste is either misleading or not helpful; remove that, and\r
+add useful comments where it’s helping.\r
+---\r
+ bindings/go/src/notmuch/notmuch.go | 737 +++++++++---------------------------\r
+ 1 file changed, 188 insertions(+), 549 deletions(-)\r
+\r
+diff --git a/bindings/go/src/notmuch/notmuch.go b/bindings/go/src/notmuch/notmuch.go\r
+index 00bd53a..0bdbba9 100644\r
+--- a/bindings/go/src/notmuch/notmuch.go\r
++++ b/bindings/go/src/notmuch/notmuch.go\r
+@@ -44,9 +44,6 @@ func (self Status) String() string {\r
+ return ""\r
+ }\r
+ \r
+-/* Various opaque data types. For each notmuch_<foo>_t see the various\r
+- * notmuch_<foo> functions below. */\r
+-\r
+ type Database struct {\r
+ db *C.notmuch_database_t\r
+ }\r
+@@ -108,23 +105,11 @@ func NewDatabase(path string) (*Database, Status) {\r
+ return self, st\r
+ }\r
+ \r
+-/* Open an existing notmuch database located at 'path'.\r
+- *\r
+- * The database should have been created at some time in the past,\r
+- * (not necessarily by this process), by calling\r
+- * notmuch_database_create with 'path'. By default the database should be\r
+- * opened for reading only. In order to write to the database you need to\r
+- * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.\r
+- *\r
+- * An existing notmuch database can be identified by the presence of a\r
+- * directory named ".notmuch" below 'path'.\r
+- *\r
+- * The caller should call notmuch_database_destroy when finished with\r
+- * this database.\r
+- *\r
+- * In case of any failure, this function returns NULL, (after printing\r
+- * an error message on stderr).\r
+- */\r
++// Open an existing notmuch database located at 'path'. By default the\r
++// database should be opened for reading only\r
++// (NOTMUCH_STATUS_READ_ONLY_DATABASE). In order to write to the\r
++// database you need to pass the NOTMUCH_DATABASE_MODE_READ_WRITE\r
++// mode.\r
+ func OpenDatabase(path string, mode DatabaseMode) (*Database, Status) {\r
+ \r
+ var c_path *C.char = C.CString(path)\r
+@@ -142,14 +127,11 @@ func OpenDatabase(path string, mode DatabaseMode) (*Database, Status) {\r
+ return self, st\r
+ }\r
+ \r
+-/* Close the given notmuch database, freeing all associated\r
+- * resources. See notmuch_database_open. */\r
+ func (self *Database) Close() {\r
+ C.notmuch_database_destroy(self.db)\r
+ }\r
+ \r
+-/* Return the database path of the given database.\r
+- */\r
++// Return the database path of the given database.\r
+ func (self *Database) GetPath() string {\r
+ \r
+ /* The return value is a string owned by notmuch so should not be\r
+@@ -162,17 +144,12 @@ func (self *Database) GetPath() string {\r
+ return ""\r
+ }\r
+ \r
+-/* Return the database format version of the given database. */\r
++// Return the database format version of the given database.\r
+ func (self *Database) GetVersion() uint {\r
+ return uint(C.notmuch_database_get_version(self.db))\r
+ }\r
+ \r
+-/* Does this database need to be upgraded before writing to it?\r
+- *\r
+- * If this function returns TRUE then no functions that modify the\r
+- * database (notmuch_database_add_message, notmuch_message_add_tag,\r
+- * notmuch_directory_set_mtime, etc.) will work unless the function\r
+- * notmuch_database_upgrade is called successfully first. */\r
++// Does this database need to be upgraded before writing to it?\r
+ func (self *Database) NeedsUpgrade() bool {\r
+ do_upgrade := C.notmuch_database_needs_upgrade(self.db)\r
+ if do_upgrade == 0 {\r
+@@ -183,14 +160,7 @@ func (self *Database) NeedsUpgrade() bool {\r
+ \r
+ // TODO: notmuch_database_upgrade\r
+ \r
+-/* Retrieve a directory object from the database for 'path'.\r
+- *\r
+- * Here, 'path' should be a path relative to the path of 'database'\r
+- * (see notmuch_database_get_path), or else should be an absolute path\r
+- * with initial components that match the path of 'database'.\r
+- *\r
+- * Can return NULL if a Xapian exception occurs.\r
+- */\r
++// Retrieve a directory object from the database for 'path'.\r
+ func (self *Database) GetDirectory(path string) (*Directory, Status) {\r
+ var c_path *C.char = C.CString(path)\r
+ defer C.free(unsafe.Pointer(c_path))\r
+@@ -207,46 +177,39 @@ func (self *Database) GetDirectory(path string) (*Directory, Status) {\r
+ return &Directory{dir: c_dir}, st\r
+ }\r
+ \r
+-/* Add a new message to the given notmuch database.\r
+- *\r
+- * Here,'filename' should be a path relative to the path of\r
+- * 'database' (see notmuch_database_get_path), or else should be an\r
+- * absolute filename with initial components that match the path of\r
+- * 'database'.\r
+- *\r
+- * The file should be a single mail message (not a multi-message mbox)\r
+- * that is expected to remain at its current location, (since the\r
+- * notmuch database will reference the filename, and will not copy the\r
+- * entire contents of the file.\r
+- *\r
+- * If 'message' is not NULL, then, on successful return '*message'\r
+- * will be initialized to a message object that can be used for things\r
+- * such as adding tags to the just-added message. The user should call\r
+- * notmuch_message_destroy when done with the message. On any failure\r
+- * '*message' will be set to NULL.\r
+- *\r
+- * Return value:\r
+- *\r
+- * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.\r
+- *\r
+- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
+- * message not added.\r
+- *\r
+- * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message\r
+- * ID as another message already in the database. The new\r
+- * filename was successfully added to the message in the database\r
+- * (if not already present).\r
+- *\r
+- * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the\r
+- * file, (such as permission denied, or file not found,\r
+- * etc.). Nothing added to the database.\r
+- *\r
+- * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look\r
+- * like an email message. Nothing added to the database.\r
+- *\r
+- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
+- * mode so no message can be added.\r
+- */\r
++// Add a new message to the given notmuch database.\r
++//\r
++// Here,'filename' should be a path relative to the path of\r
++// 'database' (see notmuch_database_get_path), or else should be an\r
++// absolute filename with initial components that match the path of\r
++// 'database'.\r
++//\r
++// The file should be a single mail message (not a multi-message mbox)\r
++// that is expected to remain at its current location, (since the\r
++// notmuch database will reference the filename, and will not copy the\r
++// entire contents of the file.)\r
++//\r
++// Return value:\r
++//\r
++// NOTMUCH_STATUS_SUCCESS: Message successfully added to database.\r
++//\r
++// NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
++// message not added.\r
++//\r
++// NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message\r
++// ID as another message already in the database. The new\r
++// filename was successfully added to the message in the database\r
++// (if not already present).\r
++//\r
++// NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the\r
++// file, (such as permission denied, or file not found,\r
++// etc.). Nothing added to the database.\r
++//\r
++// NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look\r
++// like an email message. Nothing added to the database.\r
++//\r
++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
++// mode so no message can be added.\r
+ func (self *Database) AddMessage(fname string) (*Message, Status) {\r
+ var c_fname *C.char = C.CString(fname)\r
+ defer C.free(unsafe.Pointer(c_fname))\r
+@@ -261,30 +224,29 @@ func (self *Database) AddMessage(fname string) (*Message, Status) {\r
+ return &Message{message: c_msg}, st\r
+ }\r
+ \r
+-/* Remove a message from the given notmuch database.\r
+- *\r
+- * Note that only this particular filename association is removed from\r
+- * the database. If the same message (as determined by the message ID)\r
+- * is still available via other filenames, then the message will\r
+- * persist in the database for those filenames. When the last filename\r
+- * is removed for a particular message, the database content for that\r
+- * message will be entirely removed.\r
+- *\r
+- * Return value:\r
+- *\r
+- * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the\r
+- * message was removed from the database.\r
+- *\r
+- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
+- * message not removed.\r
+- *\r
+- * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but\r
+- * the message persists in the database with at least one other\r
+- * filename.\r
+- *\r
+- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
+- * mode so no message can be removed.\r
+- */\r
++// Remove a message from the given notmuch database.\r
++//\r
++// Note that only this particular filename association is removed from\r
++// the database. If the same message (as determined by the message ID)\r
++// is still available via other filenames, then the message will\r
++// persist in the database for those filenames. When the last filename\r
++// is removed for a particular message, the database content for that\r
++// message will be entirely removed.\r
++//\r
++// Return value:\r
++//\r
++// NOTMUCH_STATUS_SUCCESS: The last filename was removed and the\r
++// message was removed from the database.\r
++//\r
++// NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
++// message not removed.\r
++//\r
++// NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but\r
++// the message persists in the database with at least one other\r
++// filename.\r
++//\r
++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
++// mode so no message can be removed.\r
+ func (self *Database) RemoveMessage(fname string) Status {\r
+ \r
+ var c_fname *C.char = C.CString(fname)\r
+@@ -298,18 +260,8 @@ func (self *Database) RemoveMessage(fname string) Status {\r
+ return Status(st)\r
+ }\r
+ \r
+-/* Find a message with the given message_id.\r
+- *\r
+- * If the database contains a message with the given message_id, then\r
+- * a new notmuch_message_t object is returned. The caller should call\r
+- * notmuch_message_destroy when done with the message.\r
+- *\r
+- * This function returns NULL in the following situations:\r
+- *\r
+- * * No message is found with the given message_id\r
+- * * An out-of-memory situation occurs\r
+- * * A Xapian exception occurs\r
+- */\r
++// Find a message with the given message_id. The caller should call\r
++// Destroy() when done with the message.\r
+ func (self *Database) FindMessage(message_id string) (*Message, Status) {\r
+ \r
+ var c_msg_id *C.char = C.CString(message_id)\r
+@@ -327,13 +279,7 @@ func (self *Database) FindMessage(message_id string) (*Message, Status) {\r
+ return msg, st\r
+ }\r
+ \r
+-/* Return a list of all tags found in the database.\r
+- *\r
+- * This function creates a list of all tags found in the database. The\r
+- * resulting list contains all tags from all messages found in the database.\r
+- *\r
+- * On error this function returns NULL.\r
+- */\r
++// Return a list of all tags found in the database.\r
+ func (self *Database) GetAllTags() *Tags {\r
+ tags := C.notmuch_database_get_all_tags(self.db)\r
+ if tags == nil {\r
+@@ -342,30 +288,8 @@ func (self *Database) GetAllTags() *Tags {\r
+ return &Tags{tags: tags}\r
+ }\r
+ \r
+-/* Create a new query for 'database'.\r
+- *\r
+- * Here, 'database' should be an open database, (see\r
+- * notmuch_database_open and notmuch_database_create).\r
+- *\r
+- * For the query string, we'll document the syntax here more\r
+- * completely in the future, but it's likely to be a specialized\r
+- * version of the general Xapian query syntax:\r
+- *\r
+- * http://xapian.org/docs/queryparser.html\r
+- *\r
+- * As a special case, passing either a length-zero string, (that is ""),\r
+- * or a string consisting of a single asterisk (that is "*"), will\r
+- * result in a query that returns all messages in the database.\r
+- *\r
+- * See notmuch_query_set_sort for controlling the order of results.\r
+- * See notmuch_query_search_messages and notmuch_query_search_threads\r
+- * to actually execute the query.\r
+- *\r
+- * User should call notmuch_query_destroy when finished with this\r
+- * query.\r
+- *\r
+- * Will return NULL if insufficient memory is available.\r
+- */\r
++// Create a new query for Database. User should call Destroy() when\r
++// finished with this query.\r
+ func (self *Database) CreateQuery(query string) *Query {\r
+ \r
+ var c_query *C.char = C.CString(query)\r
+@@ -382,7 +306,7 @@ func (self *Database) CreateQuery(query string) *Query {\r
+ return &Query{query: q}\r
+ }\r
+ \r
+-/* Sort values for notmuch_query_set_sort */\r
++// Sort values for notmuch_query_set_sort\r
+ type Sort C.notmuch_sort_t\r
+ \r
+ const (\r
+@@ -392,7 +316,6 @@ const (\r
+ SORT_UNSORTED\r
+ )\r
+ \r
+-/* Return the query_string of this query. See notmuch_query_create. */\r
+ func (self *Query) String() string {\r
+ // FIXME: do we own 'q' or not ?\r
+ q := C.notmuch_query_get_query_string(self.query)\r
+@@ -406,54 +329,28 @@ func (self *Query) String() string {\r
+ return ""\r
+ }\r
+ \r
+-/* Specify the sorting desired for this query. */\r
+ func (self *Query) SetSort(sort Sort) {\r
+ C.notmuch_query_set_sort(self.query, C.notmuch_sort_t(sort))\r
+ }\r
+ \r
+-/* Return the sort specified for this query. See notmuch_query_set_sort. */\r
+ func (self *Query) GetSort() Sort {\r
+ return Sort(C.notmuch_query_get_sort(self.query))\r
+ }\r
+ \r
+-/* Execute a query for threads, returning a notmuch_threads_t object\r
+- * which can be used to iterate over the results. The returned threads\r
+- * object is owned by the query and as such, will only be valid until\r
+- * notmuch_query_destroy.\r
+- *\r
+- * Typical usage might be:\r
+- *\r
+- * notmuch_query_t *query;\r
+- * notmuch_threads_t *threads;\r
+- * notmuch_thread_t *thread;\r
+- *\r
+- * query = notmuch_query_create (database, query_string);\r
+- *\r
+- * for (threads = notmuch_query_search_threads (query);\r
+- * notmuch_threads_valid (threads);\r
+- * notmuch_threads_move_to_next (threads))\r
+- * {\r
+- * thread = notmuch_threads_get (threads);\r
+- * ....\r
+- * notmuch_thread_destroy (thread);\r
+- * }\r
+- *\r
+- * notmuch_query_destroy (query);\r
+- *\r
+- * Note: If you are finished with a thread before its containing\r
+- * query, you can call notmuch_thread_destroy to clean up some memory\r
+- * sooner (as in the above example). Otherwise, if your thread objects\r
+- * are long-lived, then you don't need to call notmuch_thread_destroy\r
+- * and all the memory will still be reclaimed when the query is\r
+- * destroyed.\r
+- *\r
+- * Note that there's no explicit destructor needed for the\r
+- * notmuch_threads_t object. (For consistency, we do provide a\r
+- * notmuch_threads_destroy function, but there's no good reason\r
+- * to call it if the query is about to be destroyed).\r
+- *\r
+- * If a Xapian exception occurs this function will return NULL.\r
+- */\r
++// Execute a query for threads, returning a *Threads object\r
++// which can be used to iterate over the results like so:\r
++//\r
++// q := db.CreateQuery("*")\r
++// defer q.Destroy()\r
++//\r
++// ts := q.SearchThreads()\r
++// for ; ts.Valid(); ts.MoveToNext() {\r
++// t := ts.Get()\r
++// // do something here\r
++// }\r
++//\r
++// The returned object is owned by the query and as such, will only be valid\r
++// until the query is destroyed.\r
+ func (self *Query) SearchThreads() *Threads {\r
+ threads := C.notmuch_query_search_threads(self.query)\r
+ if threads == nil {\r
+@@ -462,44 +359,8 @@ func (self *Query) SearchThreads() *Threads {\r
+ return &Threads{threads: threads}\r
+ }\r
+ \r
+-/* Execute a query for messages, returning a notmuch_messages_t object\r
+- * which can be used to iterate over the results. The returned\r
+- * messages object is owned by the query and as such, will only be\r
+- * valid until notmuch_query_destroy.\r
+- *\r
+- * Typical usage might be:\r
+- *\r
+- * notmuch_query_t *query;\r
+- * notmuch_messages_t *messages;\r
+- * notmuch_message_t *message;\r
+- *\r
+- * query = notmuch_query_create (database, query_string);\r
+- *\r
+- * for (messages = notmuch_query_search_messages (query);\r
+- * notmuch_messages_valid (messages);\r
+- * notmuch_messages_move_to_next (messages))\r
+- * {\r
+- * message = notmuch_messages_get (messages);\r
+- * ....\r
+- * notmuch_message_destroy (message);\r
+- * }\r
+- *\r
+- * notmuch_query_destroy (query);\r
+- *\r
+- * Note: If you are finished with a message before its containing\r
+- * query, you can call notmuch_message_destroy to clean up some memory\r
+- * sooner (as in the above example). Otherwise, if your message\r
+- * objects are long-lived, then you don't need to call\r
+- * notmuch_message_destroy and all the memory will still be reclaimed\r
+- * when the query is destroyed.\r
+- *\r
+- * Note that there's no explicit destructor needed for the\r
+- * notmuch_messages_t object. (For consistency, we do provide a\r
+- * notmuch_messages_destroy function, but there's no good\r
+- * reason to call it if the query is about to be destroyed).\r
+- *\r
+- * If a Xapian exception occurs this function will return NULL.\r
+- */\r
++// Execute a query for messages, returning a *Messages object\r
++// which can be used to iterate over the results. See SearchThreads().\r
+ func (self *Query) SearchMessages() *Messages {\r
+ msgs := C.notmuch_query_search_messages(self.query)\r
+ if msgs == nil {\r
+@@ -508,43 +369,23 @@ func (self *Query) SearchMessages() *Messages {\r
+ return &Messages{messages: msgs}\r
+ }\r
+ \r
+-/* Destroy a notmuch_query_t along with any associated resources.\r
+- *\r
+- * This will in turn destroy any notmuch_threads_t and\r
+- * notmuch_messages_t objects generated by this query, (and in\r
+- * turn any notmuch_thread_t and notmuch_message_t objects generated\r
+- * from those results, etc.), if such objects haven't already been\r
+- * destroyed.\r
+- */\r
++// Destroy a notmuch_query_t along with any associated resources.\r
+ func (self *Query) Destroy() {\r
+ if self.query != nil {\r
+ C.notmuch_query_destroy(self.query)\r
+ }\r
+ }\r
+ \r
+-/* Return an estimate of the number of messages matching a search\r
+- *\r
+- * This function performs a search and returns Xapian's best\r
+- * guess as to number of matching messages.\r
+- *\r
+- * If a Xapian exception occurs, this function may return 0 (after\r
+- * printing a message).\r
+- */\r
++// Return an estimate of the number of messages matching a search\r
++//\r
++// This function performs a search and returns Xapian's best\r
++// guess as to number of matching messages.\r
+ func (self *Query) CountMessages() uint {\r
+ return uint(C.notmuch_query_count_messages(self.query))\r
+ }\r
+ \r
+ // TODO: wrap threads and thread\r
+ \r
+-/* Is the given 'threads' iterator pointing at a valid thread.\r
+- *\r
+- * When this function returns TRUE, notmuch_threads_get will return a\r
+- * valid object. Whereas when this function returns FALSE,\r
+- * notmuch_threads_get will return NULL.\r
+- *\r
+- * See the documentation of notmuch_query_search_threads for example\r
+- * code showing how to iterate over a notmuch_threads_t object.\r
+- */\r
+ func (self *Threads) Valid() bool {\r
+ if self.threads == nil {\r
+ return false\r
+@@ -556,27 +397,12 @@ func (self *Threads) Valid() bool {\r
+ return true\r
+ }\r
+ \r
+-/* Destroy a notmuch_threads_t object.\r
+- *\r
+- * It's not strictly necessary to call this function. All memory from\r
+- * the notmuch_threads_t object will be reclaimed when the\r
+- * containg query object is destroyed.\r
+- */\r
+ func (self *Threads) Destroy() {\r
+ if self.threads != nil {\r
+ C.notmuch_threads_destroy(self.threads)\r
+ }\r
+ }\r
+ \r
+-/* Is the given 'messages' iterator pointing at a valid message.\r
+- *\r
+- * When this function returns TRUE, notmuch_messages_get will return a\r
+- * valid object. Whereas when this function returns FALSE,\r
+- * notmuch_messages_get will return NULL.\r
+- *\r
+- * See the documentation of notmuch_query_search_messages for example\r
+- * code showing how to iterate over a notmuch_messages_t object.\r
+- */\r
+ func (self *Messages) Valid() bool {\r
+ if self.messages == nil {\r
+ return false\r
+@@ -588,17 +414,6 @@ func (self *Messages) Valid() bool {\r
+ return true\r
+ }\r
+ \r
+-/* Get the current message from 'messages' as a notmuch_message_t.\r
+- *\r
+- * Note: The returned message belongs to 'messages' and has a lifetime\r
+- * identical to it (and the query to which it belongs).\r
+- *\r
+- * See the documentation of notmuch_query_search_messages for example\r
+- * code showing how to iterate over a notmuch_messages_t object.\r
+- *\r
+- * If an out-of-memory situation occurs, this function will return\r
+- * NULL.\r
+- */\r
+ func (self *Messages) Get() *Message {\r
+ if self.messages == nil {\r
+ return nil\r
+@@ -610,16 +425,6 @@ func (self *Messages) Get() *Message {\r
+ return &Message{message: msg}\r
+ }\r
+ \r
+-/* Move the 'messages' iterator to the next message.\r
+- *\r
+- * If 'messages' is already pointing at the last message then the\r
+- * iterator will be moved to a point just beyond that last message,\r
+- * (where notmuch_messages_valid will return FALSE and\r
+- * notmuch_messages_get will return NULL).\r
+- *\r
+- * See the documentation of notmuch_query_search_messages for example\r
+- * code showing how to iterate over a notmuch_messages_t object.\r
+- */\r
+ func (self *Messages) MoveToNext() {\r
+ if self.messages == nil {\r
+ return\r
+@@ -627,30 +432,21 @@ func (self *Messages) MoveToNext() {\r
+ C.notmuch_messages_move_to_next(self.messages)\r
+ }\r
+ \r
+-/* Destroy a notmuch_messages_t object.\r
+- *\r
+- * It's not strictly necessary to call this function. All memory from\r
+- * the notmuch_messages_t object will be reclaimed when the containing\r
+- * query object is destroyed.\r
+- */\r
+ func (self *Messages) Destroy() {\r
+ if self.messages != nil {\r
+ C.notmuch_messages_destroy(self.messages)\r
+ }\r
+ }\r
+ \r
+-/* Return a list of tags from all messages.\r
+- *\r
+- * The resulting list is guaranteed not to contain duplicated tags.\r
+- *\r
+- * WARNING: You can no longer iterate over messages after calling this\r
+- * function, because the iterator will point at the end of the list.\r
+- * We do not have a function to reset the iterator yet and the only\r
+- * way how you can iterate over the list again is to recreate the\r
+- * message list.\r
+- *\r
+- * The function returns NULL on error.\r
+- */\r
++// Return a list of tags from all messages.\r
++//\r
++// The resulting list is guaranteed not to contain duplicated tags.\r
++//\r
++// WARNING: You can no longer iterate over messages after calling this\r
++// function, because the iterator will point at the end of the list.\r
++// We do not have a function to reset the iterator yet and the only\r
++// way how you can iterate over the list again is to recreate the\r
++// message list.\r
+ func (self *Messages) CollectTags() *Tags {\r
+ if self.messages == nil {\r
+ return nil\r
+@@ -662,17 +458,16 @@ func (self *Messages) CollectTags() *Tags {\r
+ return &Tags{tags: tags}\r
+ }\r
+ \r
+-/* Get the message ID of 'message'.\r
+- *\r
+- * The returned string belongs to 'message' and as such, should not be\r
+- * modified by the caller and will only be valid for as long as the\r
+- * message is valid, (which is until the query from which it derived\r
+- * is destroyed).\r
+- *\r
+- * This function will not return NULL since Notmuch ensures that every\r
+- * message has a unique message ID, (Notmuch will generate an ID for a\r
+- * message if the original file does not contain one).\r
+- */\r
++// Get the message ID of 'message'.\r
++//\r
++// The returned string belongs to 'message' and as such, should not be\r
++// modified by the caller and will only be valid for as long as the\r
++// message is valid, (which is until the query from which it derived\r
++// is destroyed).\r
++//\r
++// Notmuch ensures that every message has a unique message ID,\r
++// (Notmuch will generate an ID for a message if the original file\r
++// does not contain one).\r
+ func (self *Message) GetMessageId() string {\r
+ \r
+ if self.message == nil {\r
+@@ -687,17 +482,7 @@ func (self *Message) GetMessageId() string {\r
+ return C.GoString(id)\r
+ }\r
+ \r
+-/* Get the thread ID of 'message'.\r
+- *\r
+- * The returned string belongs to 'message' and as such, should not be\r
+- * modified by the caller and will only be valid for as long as the\r
+- * message is valid, (for example, until the user calls\r
+- * notmuch_message_destroy on 'message' or until a query from which it\r
+- * derived is destroyed).\r
+- *\r
+- * This function will not return NULL since Notmuch ensures that every\r
+- * message belongs to a single thread.\r
+- */\r
++// Get the thread ID of 'message'. See GetMessageId().\r
+ func (self *Message) GetThreadId() string {\r
+ \r
+ if self.message == nil {\r
+@@ -714,23 +499,9 @@ func (self *Message) GetThreadId() string {\r
+ return C.GoString(id)\r
+ }\r
+ \r
+-/* Get a notmuch_messages_t iterator for all of the replies to\r
+- * 'message'.\r
+- *\r
+- * Note: This call only makes sense if 'message' was ultimately\r
+- * obtained from a notmuch_thread_t object, (such as by coming\r
+- * directly from the result of calling notmuch_thread_get_\r
+- * toplevel_messages or by any number of subsequent\r
+- * calls to notmuch_message_get_replies).\r
+- *\r
+- * If 'message' was obtained through some non-thread means, (such as\r
+- * by a call to notmuch_query_search_messages), then this function\r
+- * will return NULL.\r
+- *\r
+- * If there are no replies to 'message', this function will return\r
+- * NULL. (Note that notmuch_messages_valid will accept that NULL\r
+- * value as legitimate, and simply return FALSE for it.)\r
+- */\r
++// Returns an *Messages object for all replies to the given message.\r
++// Note: This call only makes sense if the message was obtained from a\r
++// query for threads.\r
+ func (self *Message) GetReplies() *Messages {\r
+ if self.message == nil {\r
+ return nil\r
+@@ -742,20 +513,9 @@ func (self *Message) GetReplies() *Messages {\r
+ return &Messages{messages: msgs}\r
+ }\r
+ \r
+-/* Get a filename for the email corresponding to 'message'.\r
+- *\r
+- * The returned filename is an absolute filename, (the initial\r
+- * component will match notmuch_database_get_path() ).\r
+- *\r
+- * The returned string belongs to the message so should not be\r
+- * modified or freed by the caller (nor should it be referenced after\r
+- * the message is destroyed).\r
+- *\r
+- * Note: If this message corresponds to multiple files in the mail\r
+- * store, (that is, multiple files contain identical message IDs),\r
+- * this function will arbitrarily return a single one of those\r
+- * filenames.\r
+- */\r
++// Return the filename for the email corresponding to the message.\r
++// The returned filename is an absolute filename, (the initial\r
++// component will match notmuch_database_get_path() ).\r
+ func (self *Message) GetFileName() string {\r
+ if self.message == nil {\r
+ return ""\r
+@@ -777,7 +537,6 @@ const (\r
+ MESSAGE_FLAG_MATCH Flag = 0\r
+ )\r
+ \r
+-/* Get a value of a flag for the email corresponding to 'message'. */\r
+ func (self *Message) GetFlag(flag Flag) bool {\r
+ if self.message == nil {\r
+ return false\r
+@@ -789,7 +548,6 @@ func (self *Message) GetFlag(flag Flag) bool {\r
+ return true\r
+ }\r
+ \r
+-/* Set a value of a flag for the email corresponding to 'message'. */\r
+ func (self *Message) SetFlag(flag Flag, value bool) {\r
+ if self.message == nil {\r
+ return\r
+@@ -803,18 +561,12 @@ func (self *Message) SetFlag(flag Flag, value bool) {\r
+ \r
+ // TODO: wrap notmuch_message_get_date\r
+ \r
+-/* Get the value of the specified header from 'message'.\r
+- *\r
+- * The value will be read from the actual message file, not from the\r
+- * notmuch database. The header name is case insensitive.\r
+- *\r
+- * The returned string belongs to the message so should not be\r
+- * modified or freed by the caller (nor should it be referenced after\r
+- * the message is destroyed).\r
+- *\r
+- * Returns an empty string ("") if the message does not contain a\r
+- * header line matching 'header'. Returns NULL if any error occurs.\r
+- */\r
++// Get the value of the specified header from the message. The value\r
++// will be read from the actual message file, not from the notmuch\r
++// database. The header name is case insensitive.\r
++//\r
++// Returns an empty string ("") if the message does not contain a\r
++// header line matching 'header' or an error occured.\r
+ func (self *Message) GetHeader(header string) string {\r
+ if self.message == nil {\r
+ return ""\r
+@@ -832,36 +584,8 @@ func (self *Message) GetHeader(header string) string {\r
+ return C.GoString(value)\r
+ }\r
+ \r
+-/* Get the tags for 'message', returning a notmuch_tags_t object which\r
+- * can be used to iterate over all tags.\r
+- *\r
+- * The tags object is owned by the message and as such, will only be\r
+- * valid for as long as the message is valid, (which is until the\r
+- * query from which it derived is destroyed).\r
+- *\r
+- * Typical usage might be:\r
+- *\r
+- * notmuch_message_t *message;\r
+- * notmuch_tags_t *tags;\r
+- * const char *tag;\r
+- *\r
+- * message = notmuch_database_find_message (database, message_id);\r
+- *\r
+- * for (tags = notmuch_message_get_tags (message);\r
+- * notmuch_tags_valid (tags);\r
+- * notmuch_result_move_to_next (tags))\r
+- * {\r
+- * tag = notmuch_tags_get (tags);\r
+- * ....\r
+- * }\r
+- *\r
+- * notmuch_message_destroy (message);\r
+- *\r
+- * Note that there's no explicit destructor needed for the\r
+- * notmuch_tags_t object. (For consistency, we do provide a\r
+- * notmuch_tags_destroy function, but there's no good reason to call\r
+- * it if the message is about to be destroyed).\r
+- */\r
++// Get the tags for 'message', returning a *Tags object which\r
++// can be used to iterate over all tags. See SearchThreads().\r
+ func (self *Message) GetTags() *Tags {\r
+ if self.message == nil {\r
+ return nil\r
+@@ -876,20 +600,19 @@ func (self *Message) GetTags() *Tags {\r
+ /* The longest possible tag value. */\r
+ const TAG_MAX = 200\r
+ \r
+-/* Add a tag to the given message.\r
+- *\r
+- * Return value:\r
+- *\r
+- * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message\r
+- *\r
+- * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL\r
+- *\r
+- * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long\r
+- * (exceeds NOTMUCH_TAG_MAX)\r
+- *\r
+- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
+- * mode so message cannot be modified.\r
+- */\r
++// Add a tag to the given message.\r
++//\r
++// Return value:\r
++//\r
++// NOTMUCH_STATUS_SUCCESS: Tag successfully added to message\r
++//\r
++// NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL\r
++//\r
++// NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long\r
++// (exceeds NOTMUCH_TAG_MAX)\r
++//\r
++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
++// mode so message cannot be modified.\r
+ func (self *Message) AddTag(tag string) Status {\r
+ if self.message == nil {\r
+ return STATUS_NULL_POINTER\r
+@@ -900,20 +623,6 @@ func (self *Message) AddTag(tag string) Status {\r
+ return Status(C.notmuch_message_add_tag(self.message, c_tag))\r
+ }\r
+ \r
+-/* Remove a tag from the given message.\r
+- *\r
+- * Return value:\r
+- *\r
+- * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message\r
+- *\r
+- * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL\r
+- *\r
+- * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long\r
+- * (exceeds NOTMUCH_TAG_MAX)\r
+- *\r
+- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
+- * mode so message cannot be modified.\r
+- */\r
+ func (self *Message) RemoveTag(tag string) Status {\r
+ if self.message == nil {\r
+ return STATUS_NULL_POINTER\r
+@@ -924,14 +633,6 @@ func (self *Message) RemoveTag(tag string) Status {\r
+ return Status(C.notmuch_message_remove_tag(self.message, c_tag))\r
+ }\r
+ \r
+-/* Remove all tags from the given message.\r
+- *\r
+- * See notmuch_message_freeze for an example showing how to safely\r
+- * replace tag values.\r
+- *\r
+- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
+- * mode so message cannot be modified.\r
+- */\r
+ func (self *Message) RemoveAllTags() Status {\r
+ if self.message == nil {\r
+ return STATUS_NULL_POINTER\r
+@@ -939,46 +640,44 @@ func (self *Message) RemoveAllTags() Status {\r
+ return Status(C.notmuch_message_remove_all_tags(self.message))\r
+ }\r
+ \r
+-/* Freeze the current state of 'message' within the database.\r
+- *\r
+- * This means that changes to the message state, (via\r
+- * notmuch_message_add_tag, notmuch_message_remove_tag, and\r
+- * notmuch_message_remove_all_tags), will not be committed to the\r
+- * database until the message is thawed with notmuch_message_thaw.\r
+- *\r
+- * Multiple calls to freeze/thaw are valid and these calls will\r
+- * "stack". That is there must be as many calls to thaw as to freeze\r
+- * before a message is actually thawed.\r
+- *\r
+- * The ability to do freeze/thaw allows for safe transactions to\r
+- * change tag values. For example, explicitly setting a message to\r
+- * have a given set of tags might look like this:\r
+- *\r
+- * notmuch_message_freeze (message);\r
+- *\r
+- * notmuch_message_remove_all_tags (message);\r
+- *\r
+- * for (i = 0; i < NUM_TAGS; i++)\r
+- * notmuch_message_add_tag (message, tags[i]);\r
+- *\r
+- * notmuch_message_thaw (message);\r
+- *\r
+- * With freeze/thaw used like this, the message in the database is\r
+- * guaranteed to have either the full set of original tag values, or\r
+- * the full set of new tag values, but nothing in between.\r
+- *\r
+- * Imagine the example above without freeze/thaw and the operation\r
+- * somehow getting interrupted. This could result in the message being\r
+- * left with no tags if the interruption happened after\r
+- * notmuch_message_remove_all_tags but before notmuch_message_add_tag.\r
+- *\r
+- * Return value:\r
+- *\r
+- * NOTMUCH_STATUS_SUCCESS: Message successfully frozen.\r
+- *\r
+- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
+- * mode so message cannot be modified.\r
+- */\r
++// Freeze the current state of the message within the database.\r
++//\r
++// This means that changes to the message state will not be committed\r
++// to the database until the message is thawed with Thaw().\r
++//\r
++// Multiple calls to freeze/thaw are valid and these calls will\r
++// "stack". That is there must be as many calls to thaw as to freeze\r
++// before a message is actually thawed.\r
++//\r
++// The ability to do freeze/thaw allows for safe transactions to\r
++// change tag values. For example, explicitly setting a message to\r
++// have a given set of tags might look like this:\r
++//\r
++// notmuch_message_freeze (message);\r
++//\r
++// notmuch_message_remove_all_tags (message);\r
++//\r
++// for (i = 0; i < NUM_TAGS; i++)\r
++// notmuch_message_add_tag (message, tags[i]);\r
++//\r
++// notmuch_message_thaw (message);\r
++//\r
++// With freeze/thaw used like this, the message in the database is\r
++// guaranteed to have either the full set of original tag values, or\r
++// the full set of new tag values, but nothing in between.\r
++//\r
++// Imagine the example above without freeze/thaw and the operation\r
++// somehow getting interrupted. This could result in the message being\r
++// left with no tags if the interruption happened after\r
++// notmuch_message_remove_all_tags but before notmuch_message_add_tag.\r
++//\r
++// Return value:\r
++//\r
++// NOTMUCH_STATUS_SUCCESS: Message successfully frozen.\r
++//\r
++// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
++// mode so message cannot be modified.\r
++///\r
+ func (self *Message) Freeze() Status {\r
+ if self.message == nil {\r
+ return STATUS_NULL_POINTER\r
+@@ -986,26 +685,8 @@ func (self *Message) Freeze() Status {\r
+ return Status(C.notmuch_message_freeze(self.message))\r
+ }\r
+ \r
+-/* Thaw the current 'message', synchronizing any changes that may have\r
+- * occurred while 'message' was frozen into the notmuch database.\r
+- *\r
+- * See notmuch_message_freeze for an example of how to use this\r
+- * function to safely provide tag changes.\r
+- *\r
+- * Multiple calls to freeze/thaw are valid and these calls with\r
+- * "stack". That is there must be as many calls to thaw as to freeze\r
+- * before a message is actually thawed.\r
+- *\r
+- * Return value:\r
+- *\r
+- * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least\r
+- * its frozen count has successfully been reduced by 1).\r
+- *\r
+- * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw\r
+- * an unfrozen message. That is, there have been an unbalanced\r
+- * number of calls to notmuch_message_freeze and\r
+- * notmuch_message_thaw.\r
+- */\r
++// Thaw the current 'message', synchronizing any changes that may have\r
++// occurred while 'message' was frozen into the notmuch database.\r
+ func (self *Message) Thaw() Status {\r
+ if self.message == nil {\r
+ return STATUS_NULL_POINTER\r
+@@ -1014,14 +695,13 @@ func (self *Message) Thaw() Status {\r
+ return Status(C.notmuch_message_thaw(self.message))\r
+ }\r
+ \r
+-/* Destroy a notmuch_message_t object.\r
+- *\r
+- * It can be useful to call this function in the case of a single\r
+- * query object with many messages in the result, (such as iterating\r
+- * over the entire database). Otherwise, it's fine to never call this\r
+- * function and there will still be no memory leaks. (The memory from\r
+- * the messages get reclaimed when the containing query is destroyed.)\r
+- */\r
++// Destroy a notmuch_message_t object.\r
++//\r
++// It can be useful to call this function in the case of a single\r
++// query object with many messages in the result, (such as iterating\r
++// over the entire database). Otherwise, it's fine to never call this\r
++// function and there will still be no memory leaks. (The memory from\r
++// the messages get reclaimed when the containing query is destroyed.)\r
+ func (self *Message) Destroy() {\r
+ if self.message == nil {\r
+ return\r
+@@ -1029,15 +709,6 @@ func (self *Message) Destroy() {\r
+ C.notmuch_message_destroy(self.message)\r
+ }\r
+ \r
+-/* Is the given 'tags' iterator pointing at a valid tag.\r
+- *\r
+- * When this function returns TRUE, notmuch_tags_get will return a\r
+- * valid string. Whereas when this function returns FALSE,\r
+- * notmuch_tags_get will return NULL.\r
+- *\r
+- * See the documentation of notmuch_message_get_tags for example code\r
+- * showing how to iterate over a notmuch_tags_t object.\r
+- */\r
+ func (self *Tags) Valid() bool {\r
+ if self.tags == nil {\r
+ return false\r
+@@ -1049,14 +720,6 @@ func (self *Tags) Valid() bool {\r
+ return true\r
+ }\r
+ \r
+-/* Get the current tag from 'tags' as a string.\r
+- *\r
+- * Note: The returned string belongs to 'tags' and has a lifetime\r
+- * identical to it (and the query to which it ultimately belongs).\r
+- *\r
+- * See the documentation of notmuch_message_get_tags for example code\r
+- * showing how to iterate over a notmuch_tags_t object.\r
+- */\r
+ func (self *Tags) Get() string {\r
+ if self.tags == nil {\r
+ return ""\r
+@@ -1066,20 +729,11 @@ func (self *Tags) Get() string {\r
+ \r
+ return C.GoString(s)\r
+ }\r
++\r
+ func (self *Tags) String() string {\r
+ return self.Get()\r
+ }\r
+ \r
+-/* Move the 'tags' iterator to the next tag.\r
+- *\r
+- * If 'tags' is already pointing at the last tag then the iterator\r
+- * will be moved to a point just beyond that last tag, (where\r
+- * notmuch_tags_valid will return FALSE and notmuch_tags_get will\r
+- * return NULL).\r
+- *\r
+- * See the documentation of notmuch_message_get_tags for example code\r
+- * showing how to iterate over a notmuch_tags_t object.\r
+- */\r
+ func (self *Tags) MoveToNext() {\r
+ if self.tags == nil {\r
+ return\r
+@@ -1087,12 +741,6 @@ func (self *Tags) MoveToNext() {\r
+ C.notmuch_tags_move_to_next(self.tags)\r
+ }\r
+ \r
+-/* Destroy a notmuch_tags_t object.\r
+- *\r
+- * It's not strictly necessary to call this function. All memory from\r
+- * the notmuch_tags_t object will be reclaimed when the containing\r
+- * message or query objects are destroyed.\r
+- */\r
+ func (self *Tags) Destroy() {\r
+ if self.tags == nil {\r
+ return\r
+@@ -1102,7 +750,7 @@ func (self *Tags) Destroy() {\r
+ \r
+ // TODO: wrap notmuch_directory_<fct>\r
+ \r
+-/* Destroy a notmuch_directory_t object. */\r
++// Destroy a notmuch_directory_t object.\r
+ func (self *Directory) Destroy() {\r
+ if self.dir == nil {\r
+ return\r
+@@ -1112,15 +760,6 @@ func (self *Directory) Destroy() {\r
+ \r
+ // TODO: wrap notmuch_filenames_<fct>\r
+ \r
+-/* Destroy a notmuch_filenames_t object.\r
+- *\r
+- * It's not strictly necessary to call this function. All memory from\r
+- * the notmuch_filenames_t object will be reclaimed when the\r
+- * containing directory object is destroyed.\r
+- *\r
+- * It is acceptable to pass NULL for 'filenames', in which case this\r
+- * function will do nothing.\r
+- */\r
+ func (self *Filenames) Destroy() {\r
+ if self.fnames == nil {\r
+ return\r
+-- \r
+1.7.10.4\r
+\r
projects / notmuch-archives.git / commitdiff