6a/0bc385b8485c933850effd5497c639744f96fd

   1 Return-Path: <feh@noam.feh.name>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 34CC8431FBF\r
   6         for <notmuch@notmuchmail.org>; Sat,  2 Mar 2013 06:57:37 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: 0\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]\r
  12         autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id LVbPBZBrfe5w for <notmuch@notmuchmail.org>;\r
  16         Sat,  2 Mar 2013 06:57:32 -0800 (PST)\r
  17 X-Greylist: delayed 375 seconds by postgrey-1.32 at olra;\r
  18         Sat, 02 Mar 2013 06:57:27 PST\r
  19 Received: from noam.feh.name (noam.feh.name [176.9.34.52])\r
  20         by olra.theworths.org (Postfix) with ESMTP id EE2C5431FAE\r
  21         for <notmuch@notmuchmail.org>; Sat,  2 Mar 2013 06:57:27 -0800 (PST)\r
  22 Received: by noam.feh.name (Postfix, from userid 1000)\r
  23         id 9C487157C123; Sat,  2 Mar 2013 15:51:11 +0100 (CET)\r
  24 From: Julius Plenz <julius@plenz.com>\r
  25 To: notmuch@notmuchmail.org\r
  26 Subject: [PATCH 1/3] Go bindings: clean up the documentation\r
  27 Date: Sat,  2 Mar 2013 15:50:54 +0100\r
  28 Message-Id: <1362235856-15358-1-git-send-email-julius@plenz.com>\r
  29 X-Mailer: git-send-email 1.7.2.5\r
  30 MIME-Version: 1.0\r
  31 Content-Type: text/plain; charset=UTF-8\r
  32 Content-Transfer-Encoding: 8bit\r
  33 X-Mailman-Approved-At: Sat, 02 Mar 2013 09:47:30 -0800\r
  34 Cc: Julius Plenz <julius@plenz.com>\r
  35 X-BeenThere: notmuch@notmuchmail.org\r
  36 X-Mailman-Version: 2.1.13\r
  37 Precedence: list\r
  38 List-Id: "Use and development of the notmuch mail system."\r
  39         <notmuch.notmuchmail.org>\r
  40 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  41         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  42 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  43 List-Post: <mailto:notmuch@notmuchmail.org>\r
  44 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  45 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  46         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  47 X-List-Received-Date: Sat, 02 Mar 2013 14:57:37 -0000\r
  48 \r
  49 Most of the copy&paste is either misleading or not helpful; remove that, and\r
  50 add useful comments where it’s helping.\r
  51 ---\r
  52  bindings/go/src/notmuch/notmuch.go |  737 +++++++++---------------------------\r
  53  1 file changed, 188 insertions(+), 549 deletions(-)\r
  54 \r
  55 diff --git a/bindings/go/src/notmuch/notmuch.go b/bindings/go/src/notmuch/notmuch.go\r
  56 index 00bd53a..0bdbba9 100644\r
  57 --- a/bindings/go/src/notmuch/notmuch.go\r
  58 +++ b/bindings/go/src/notmuch/notmuch.go\r
  59 @@ -44,9 +44,6 @@ func (self Status) String() string {\r
  60         return ""\r
  61  }\r
  62  \r
  63 -/* Various opaque data types. For each notmuch_<foo>_t see the various\r
  64 - * notmuch_<foo> functions below. */\r
  65 -\r
  66  type Database struct {\r
  67         db *C.notmuch_database_t\r
  68  }\r
  69 @@ -108,23 +105,11 @@ func NewDatabase(path string) (*Database, Status) {\r
  70         return self, st\r
  71  }\r
  72  \r
  73 -/* Open an existing notmuch database located at 'path'.\r
  74 - *\r
  75 - * The database should have been created at some time in the past,\r
  76 - * (not necessarily by this process), by calling\r
  77 - * notmuch_database_create with 'path'. By default the database should be\r
  78 - * opened for reading only. In order to write to the database you need to\r
  79 - * pass the NOTMUCH_DATABASE_MODE_READ_WRITE mode.\r
  80 - *\r
  81 - * An existing notmuch database can be identified by the presence of a\r
  82 - * directory named ".notmuch" below 'path'.\r
  83 - *\r
  84 - * The caller should call notmuch_database_destroy when finished with\r
  85 - * this database.\r
  86 - *\r
  87 - * In case of any failure, this function returns NULL, (after printing\r
  88 - * an error message on stderr).\r
  89 - */\r
  90 +// Open an existing notmuch database located at 'path'. By default the\r
  91 +// database should be opened for reading only\r
  92 +// (NOTMUCH_STATUS_READ_ONLY_DATABASE). In order to write to the\r
  93 +// database you need to pass the NOTMUCH_DATABASE_MODE_READ_WRITE\r
  94 +// mode.\r
  95  func OpenDatabase(path string, mode DatabaseMode) (*Database, Status) {\r
  96  \r
  97         var c_path *C.char = C.CString(path)\r
  98 @@ -142,14 +127,11 @@ func OpenDatabase(path string, mode DatabaseMode) (*Database, Status) {\r
  99         return self, st\r
 100  }\r
 101  \r
 102 -/* Close the given notmuch database, freeing all associated\r
 103 - * resources. See notmuch_database_open. */\r
 104  func (self *Database) Close() {\r
 105         C.notmuch_database_destroy(self.db)\r
 106  }\r
 107  \r
 108 -/* Return the database path of the given database.\r
 109 - */\r
 110 +// Return the database path of the given database.\r
 111  func (self *Database) GetPath() string {\r
 112  \r
 113         /* The return value is a string owned by notmuch so should not be\r
 114 @@ -162,17 +144,12 @@ func (self *Database) GetPath() string {\r
 115         return ""\r
 116  }\r
 117  \r
 118 -/* Return the database format version of the given database. */\r
 119 +// Return the database format version of the given database.\r
 120  func (self *Database) GetVersion() uint {\r
 121         return uint(C.notmuch_database_get_version(self.db))\r
 122  }\r
 123  \r
 124 -/* Does this database need to be upgraded before writing to it?\r
 125 - *\r
 126 - * If this function returns TRUE then no functions that modify the\r
 127 - * database (notmuch_database_add_message, notmuch_message_add_tag,\r
 128 - * notmuch_directory_set_mtime, etc.) will work unless the function\r
 129 - * notmuch_database_upgrade is called successfully first. */\r
 130 +// Does this database need to be upgraded before writing to it?\r
 131  func (self *Database) NeedsUpgrade() bool {\r
 132         do_upgrade := C.notmuch_database_needs_upgrade(self.db)\r
 133         if do_upgrade == 0 {\r
 134 @@ -183,14 +160,7 @@ func (self *Database) NeedsUpgrade() bool {\r
 135  \r
 136  // TODO: notmuch_database_upgrade\r
 137  \r
 138 -/* Retrieve a directory object from the database for 'path'.\r
 139 - *\r
 140 - * Here, 'path' should be a path relative to the path of 'database'\r
 141 - * (see notmuch_database_get_path), or else should be an absolute path\r
 142 - * with initial components that match the path of 'database'.\r
 143 - *\r
 144 - * Can return NULL if a Xapian exception occurs.\r
 145 - */\r
 146 +// Retrieve a directory object from the database for 'path'.\r
 147  func (self *Database) GetDirectory(path string) (*Directory, Status) {\r
 148         var c_path *C.char = C.CString(path)\r
 149         defer C.free(unsafe.Pointer(c_path))\r
 150 @@ -207,46 +177,39 @@ func (self *Database) GetDirectory(path string) (*Directory, Status) {\r
 151         return &Directory{dir: c_dir}, st\r
 152  }\r
 153  \r
 154 -/* Add a new message to the given notmuch database.\r
 155 - *\r
 156 - * Here,'filename' should be a path relative to the path of\r
 157 - * 'database' (see notmuch_database_get_path), or else should be an\r
 158 - * absolute filename with initial components that match the path of\r
 159 - * 'database'.\r
 160 - *\r
 161 - * The file should be a single mail message (not a multi-message mbox)\r
 162 - * that is expected to remain at its current location, (since the\r
 163 - * notmuch database will reference the filename, and will not copy the\r
 164 - * entire contents of the file.\r
 165 - *\r
 166 - * If 'message' is not NULL, then, on successful return '*message'\r
 167 - * will be initialized to a message object that can be used for things\r
 168 - * such as adding tags to the just-added message. The user should call\r
 169 - * notmuch_message_destroy when done with the message. On any failure\r
 170 - * '*message' will be set to NULL.\r
 171 - *\r
 172 - * Return value:\r
 173 - *\r
 174 - * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.\r
 175 - *\r
 176 - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
 177 - *     message not added.\r
 178 - *\r
 179 - * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message\r
 180 - *     ID as another message already in the database. The new\r
 181 - *     filename was successfully added to the message in the database\r
 182 - *     (if not already present).\r
 183 - *\r
 184 - * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the\r
 185 - *     file, (such as permission denied, or file not found,\r
 186 - *     etc.). Nothing added to the database.\r
 187 - *\r
 188 - * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look\r
 189 - *     like an email message. Nothing added to the database.\r
 190 - *\r
 191 - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 192 - *     mode so no message can be added.\r
 193 - */\r
 194 +// Add a new message to the given notmuch database.\r
 195 +//\r
 196 +// Here,'filename' should be a path relative to the path of\r
 197 +// 'database' (see notmuch_database_get_path), or else should be an\r
 198 +// absolute filename with initial components that match the path of\r
 199 +// 'database'.\r
 200 +//\r
 201 +// The file should be a single mail message (not a multi-message mbox)\r
 202 +// that is expected to remain at its current location, (since the\r
 203 +// notmuch database will reference the filename, and will not copy the\r
 204 +// entire contents of the file.)\r
 205 +//\r
 206 +// Return value:\r
 207 +//\r
 208 +// NOTMUCH_STATUS_SUCCESS: Message successfully added to database.\r
 209 +//\r
 210 +// NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
 211 +// message not added.\r
 212 +//\r
 213 +// NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message\r
 214 +// ID as another message already in the database. The new\r
 215 +// filename was successfully added to the message in the database\r
 216 +// (if not already present).\r
 217 +//\r
 218 +// NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the\r
 219 +// file, (such as permission denied, or file not found,\r
 220 +// etc.). Nothing added to the database.\r
 221 +//\r
 222 +// NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look\r
 223 +// like an email message. Nothing added to the database.\r
 224 +//\r
 225 +// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 226 +// mode so no message can be added.\r
 227  func (self *Database) AddMessage(fname string) (*Message, Status) {\r
 228         var c_fname *C.char = C.CString(fname)\r
 229         defer C.free(unsafe.Pointer(c_fname))\r
 230 @@ -261,30 +224,29 @@ func (self *Database) AddMessage(fname string) (*Message, Status) {\r
 231         return &Message{message: c_msg}, st\r
 232  }\r
 233  \r
 234 -/* Remove a message from the given notmuch database.\r
 235 - *\r
 236 - * Note that only this particular filename association is removed from\r
 237 - * the database. If the same message (as determined by the message ID)\r
 238 - * is still available via other filenames, then the message will\r
 239 - * persist in the database for those filenames. When the last filename\r
 240 - * is removed for a particular message, the database content for that\r
 241 - * message will be entirely removed.\r
 242 - *\r
 243 - * Return value:\r
 244 - *\r
 245 - * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the\r
 246 - *     message was removed from the database.\r
 247 - *\r
 248 - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
 249 - *     message not removed.\r
 250 - *\r
 251 - * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but\r
 252 - *     the message persists in the database with at least one other\r
 253 - *     filename.\r
 254 - *\r
 255 - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 256 - *     mode so no message can be removed.\r
 257 - */\r
 258 +// Remove a message from the given notmuch database.\r
 259 +//\r
 260 +// Note that only this particular filename association is removed from\r
 261 +// the database. If the same message (as determined by the message ID)\r
 262 +// is still available via other filenames, then the message will\r
 263 +// persist in the database for those filenames. When the last filename\r
 264 +// is removed for a particular message, the database content for that\r
 265 +// message will be entirely removed.\r
 266 +//\r
 267 +// Return value:\r
 268 +//\r
 269 +// NOTMUCH_STATUS_SUCCESS: The last filename was removed and the\r
 270 +// message was removed from the database.\r
 271 +//\r
 272 +// NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,\r
 273 +// message not removed.\r
 274 +//\r
 275 +// NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but\r
 276 +// the message persists in the database with at least one other\r
 277 +// filename.\r
 278 +//\r
 279 +// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 280 +// mode so no message can be removed.\r
 281  func (self *Database) RemoveMessage(fname string) Status {\r
 282  \r
 283         var c_fname *C.char = C.CString(fname)\r
 284 @@ -298,18 +260,8 @@ func (self *Database) RemoveMessage(fname string) Status {\r
 285         return Status(st)\r
 286  }\r
 287  \r
 288 -/* Find a message with the given message_id.\r
 289 - *\r
 290 - * If the database contains a message with the given message_id, then\r
 291 - * a new notmuch_message_t object is returned. The caller should call\r
 292 - * notmuch_message_destroy when done with the message.\r
 293 - *\r
 294 - * This function returns NULL in the following situations:\r
 295 - *\r
 296 - *     * No message is found with the given message_id\r
 297 - *     * An out-of-memory situation occurs\r
 298 - *     * A Xapian exception occurs\r
 299 - */\r
 300 +// Find a message with the given message_id. The caller should call\r
 301 +// Destroy() when done with the message.\r
 302  func (self *Database) FindMessage(message_id string) (*Message, Status) {\r
 303  \r
 304         var c_msg_id *C.char = C.CString(message_id)\r
 305 @@ -327,13 +279,7 @@ func (self *Database) FindMessage(message_id string) (*Message, Status) {\r
 306         return msg, st\r
 307  }\r
 308  \r
 309 -/* Return a list of all tags found in the database.\r
 310 - *\r
 311 - * This function creates a list of all tags found in the database. The\r
 312 - * resulting list contains all tags from all messages found in the database.\r
 313 - *\r
 314 - * On error this function returns NULL.\r
 315 - */\r
 316 +// Return a list of all tags found in the database.\r
 317  func (self *Database) GetAllTags() *Tags {\r
 318         tags := C.notmuch_database_get_all_tags(self.db)\r
 319         if tags == nil {\r
 320 @@ -342,30 +288,8 @@ func (self *Database) GetAllTags() *Tags {\r
 321         return &Tags{tags: tags}\r
 322  }\r
 323  \r
 324 -/* Create a new query for 'database'.\r
 325 - *\r
 326 - * Here, 'database' should be an open database, (see\r
 327 - * notmuch_database_open and notmuch_database_create).\r
 328 - *\r
 329 - * For the query string, we'll document the syntax here more\r
 330 - * completely in the future, but it's likely to be a specialized\r
 331 - * version of the general Xapian query syntax:\r
 332 - *\r
 333 - * http://xapian.org/docs/queryparser.html\r
 334 - *\r
 335 - * As a special case, passing either a length-zero string, (that is ""),\r
 336 - * or a string consisting of a single asterisk (that is "*"), will\r
 337 - * result in a query that returns all messages in the database.\r
 338 - *\r
 339 - * See notmuch_query_set_sort for controlling the order of results.\r
 340 - * See notmuch_query_search_messages and notmuch_query_search_threads\r
 341 - * to actually execute the query.\r
 342 - *\r
 343 - * User should call notmuch_query_destroy when finished with this\r
 344 - * query.\r
 345 - *\r
 346 - * Will return NULL if insufficient memory is available.\r
 347 - */\r
 348 +// Create a new query for Database. User should call Destroy() when\r
 349 +// finished with this query.\r
 350  func (self *Database) CreateQuery(query string) *Query {\r
 351  \r
 352         var c_query *C.char = C.CString(query)\r
 353 @@ -382,7 +306,7 @@ func (self *Database) CreateQuery(query string) *Query {\r
 354         return &Query{query: q}\r
 355  }\r
 356  \r
 357 -/* Sort values for notmuch_query_set_sort */\r
 358 +// Sort values for notmuch_query_set_sort\r
 359  type Sort C.notmuch_sort_t\r
 360  \r
 361  const (\r
 362 @@ -392,7 +316,6 @@ const (\r
 363         SORT_UNSORTED\r
 364  )\r
 365  \r
 366 -/* Return the query_string of this query. See notmuch_query_create. */\r
 367  func (self *Query) String() string {\r
 368         // FIXME: do we own 'q' or not ?\r
 369         q := C.notmuch_query_get_query_string(self.query)\r
 370 @@ -406,54 +329,28 @@ func (self *Query) String() string {\r
 371         return ""\r
 372  }\r
 373  \r
 374 -/* Specify the sorting desired for this query. */\r
 375  func (self *Query) SetSort(sort Sort) {\r
 376         C.notmuch_query_set_sort(self.query, C.notmuch_sort_t(sort))\r
 377  }\r
 378  \r
 379 -/* Return the sort specified for this query. See notmuch_query_set_sort. */\r
 380  func (self *Query) GetSort() Sort {\r
 381         return Sort(C.notmuch_query_get_sort(self.query))\r
 382  }\r
 383  \r
 384 -/* Execute a query for threads, returning a notmuch_threads_t object\r
 385 - * which can be used to iterate over the results. The returned threads\r
 386 - * object is owned by the query and as such, will only be valid until\r
 387 - * notmuch_query_destroy.\r
 388 - *\r
 389 - * Typical usage might be:\r
 390 - *\r
 391 - *     notmuch_query_t *query;\r
 392 - *     notmuch_threads_t *threads;\r
 393 - *     notmuch_thread_t *thread;\r
 394 - *\r
 395 - *     query = notmuch_query_create (database, query_string);\r
 396 - *\r
 397 - *     for (threads = notmuch_query_search_threads (query);\r
 398 - *          notmuch_threads_valid (threads);\r
 399 - *          notmuch_threads_move_to_next (threads))\r
 400 - *     {\r
 401 - *         thread = notmuch_threads_get (threads);\r
 402 - *         ....\r
 403 - *         notmuch_thread_destroy (thread);\r
 404 - *     }\r
 405 - *\r
 406 - *     notmuch_query_destroy (query);\r
 407 - *\r
 408 - * Note: If you are finished with a thread before its containing\r
 409 - * query, you can call notmuch_thread_destroy to clean up some memory\r
 410 - * sooner (as in the above example). Otherwise, if your thread objects\r
 411 - * are long-lived, then you don't need to call notmuch_thread_destroy\r
 412 - * and all the memory will still be reclaimed when the query is\r
 413 - * destroyed.\r
 414 - *\r
 415 - * Note that there's no explicit destructor needed for the\r
 416 - * notmuch_threads_t object. (For consistency, we do provide a\r
 417 - * notmuch_threads_destroy function, but there's no good reason\r
 418 - * to call it if the query is about to be destroyed).\r
 419 - *\r
 420 - * If a Xapian exception occurs this function will return NULL.\r
 421 - */\r
 422 +// Execute a query for threads, returning a *Threads object\r
 423 +// which can be used to iterate over the results like so:\r
 424 +//\r
 425 +//     q := db.CreateQuery("*")\r
 426 +//     defer q.Destroy()\r
 427 +//\r
 428 +//     ts := q.SearchThreads()\r
 429 +//     for ; ts.Valid(); ts.MoveToNext() {\r
 430 +//             t := ts.Get()\r
 431 +//             // do something here\r
 432 +//     }\r
 433 +//\r
 434 +// The returned object is owned by the query and as such, will only be valid\r
 435 +// until the query is destroyed.\r
 436  func (self *Query) SearchThreads() *Threads {\r
 437         threads := C.notmuch_query_search_threads(self.query)\r
 438         if threads == nil {\r
 439 @@ -462,44 +359,8 @@ func (self *Query) SearchThreads() *Threads {\r
 440         return &Threads{threads: threads}\r
 441  }\r
 442  \r
 443 -/* Execute a query for messages, returning a notmuch_messages_t object\r
 444 - * which can be used to iterate over the results. The returned\r
 445 - * messages object is owned by the query and as such, will only be\r
 446 - * valid until notmuch_query_destroy.\r
 447 - *\r
 448 - * Typical usage might be:\r
 449 - *\r
 450 - *     notmuch_query_t *query;\r
 451 - *     notmuch_messages_t *messages;\r
 452 - *     notmuch_message_t *message;\r
 453 - *\r
 454 - *     query = notmuch_query_create (database, query_string);\r
 455 - *\r
 456 - *     for (messages = notmuch_query_search_messages (query);\r
 457 - *          notmuch_messages_valid (messages);\r
 458 - *          notmuch_messages_move_to_next (messages))\r
 459 - *     {\r
 460 - *         message = notmuch_messages_get (messages);\r
 461 - *         ....\r
 462 - *         notmuch_message_destroy (message);\r
 463 - *     }\r
 464 - *\r
 465 - *     notmuch_query_destroy (query);\r
 466 - *\r
 467 - * Note: If you are finished with a message before its containing\r
 468 - * query, you can call notmuch_message_destroy to clean up some memory\r
 469 - * sooner (as in the above example). Otherwise, if your message\r
 470 - * objects are long-lived, then you don't need to call\r
 471 - * notmuch_message_destroy and all the memory will still be reclaimed\r
 472 - * when the query is destroyed.\r
 473 - *\r
 474 - * Note that there's no explicit destructor needed for the\r
 475 - * notmuch_messages_t object. (For consistency, we do provide a\r
 476 - * notmuch_messages_destroy function, but there's no good\r
 477 - * reason to call it if the query is about to be destroyed).\r
 478 - *\r
 479 - * If a Xapian exception occurs this function will return NULL.\r
 480 - */\r
 481 +// Execute a query for messages, returning a *Messages object\r
 482 +// which can be used to iterate over the results. See SearchThreads().\r
 483  func (self *Query) SearchMessages() *Messages {\r
 484         msgs := C.notmuch_query_search_messages(self.query)\r
 485         if msgs == nil {\r
 486 @@ -508,43 +369,23 @@ func (self *Query) SearchMessages() *Messages {\r
 487         return &Messages{messages: msgs}\r
 488  }\r
 489  \r
 490 -/* Destroy a notmuch_query_t along with any associated resources.\r
 491 - *\r
 492 - * This will in turn destroy any notmuch_threads_t and\r
 493 - * notmuch_messages_t objects generated by this query, (and in\r
 494 - * turn any notmuch_thread_t and notmuch_message_t objects generated\r
 495 - * from those results, etc.), if such objects haven't already been\r
 496 - * destroyed.\r
 497 - */\r
 498 +// Destroy a notmuch_query_t along with any associated resources.\r
 499  func (self *Query) Destroy() {\r
 500         if self.query != nil {\r
 501                 C.notmuch_query_destroy(self.query)\r
 502         }\r
 503  }\r
 504  \r
 505 -/* Return an estimate of the number of messages matching a search\r
 506 - *\r
 507 - * This function performs a search and returns Xapian's best\r
 508 - * guess as to number of matching messages.\r
 509 - *\r
 510 - * If a Xapian exception occurs, this function may return 0 (after\r
 511 - * printing a message).\r
 512 - */\r
 513 +// Return an estimate of the number of messages matching a search\r
 514 +//\r
 515 +// This function performs a search and returns Xapian's best\r
 516 +// guess as to number of matching messages.\r
 517  func (self *Query) CountMessages() uint {\r
 518         return uint(C.notmuch_query_count_messages(self.query))\r
 519  }\r
 520  \r
 521  // TODO: wrap threads and thread\r
 522  \r
 523 -/* Is the given 'threads' iterator pointing at a valid thread.\r
 524 - *\r
 525 - * When this function returns TRUE, notmuch_threads_get will return a\r
 526 - * valid object. Whereas when this function returns FALSE,\r
 527 - * notmuch_threads_get will return NULL.\r
 528 - *\r
 529 - * See the documentation of notmuch_query_search_threads for example\r
 530 - * code showing how to iterate over a notmuch_threads_t object.\r
 531 - */\r
 532  func (self *Threads) Valid() bool {\r
 533         if self.threads == nil {\r
 534                 return false\r
 535 @@ -556,27 +397,12 @@ func (self *Threads) Valid() bool {\r
 536         return true\r
 537  }\r
 538  \r
 539 -/* Destroy a notmuch_threads_t object.\r
 540 - *\r
 541 - * It's not strictly necessary to call this function. All memory from\r
 542 - * the notmuch_threads_t object will be reclaimed when the\r
 543 - * containg query object is destroyed.\r
 544 - */\r
 545  func (self *Threads) Destroy() {\r
 546         if self.threads != nil {\r
 547                 C.notmuch_threads_destroy(self.threads)\r
 548         }\r
 549  }\r
 550  \r
 551 -/* Is the given 'messages' iterator pointing at a valid message.\r
 552 - *\r
 553 - * When this function returns TRUE, notmuch_messages_get will return a\r
 554 - * valid object. Whereas when this function returns FALSE,\r
 555 - * notmuch_messages_get will return NULL.\r
 556 - *\r
 557 - * See the documentation of notmuch_query_search_messages for example\r
 558 - * code showing how to iterate over a notmuch_messages_t object.\r
 559 - */\r
 560  func (self *Messages) Valid() bool {\r
 561         if self.messages == nil {\r
 562                 return false\r
 563 @@ -588,17 +414,6 @@ func (self *Messages) Valid() bool {\r
 564         return true\r
 565  }\r
 566  \r
 567 -/* Get the current message from 'messages' as a notmuch_message_t.\r
 568 - *\r
 569 - * Note: The returned message belongs to 'messages' and has a lifetime\r
 570 - * identical to it (and the query to which it belongs).\r
 571 - *\r
 572 - * See the documentation of notmuch_query_search_messages for example\r
 573 - * code showing how to iterate over a notmuch_messages_t object.\r
 574 - *\r
 575 - * If an out-of-memory situation occurs, this function will return\r
 576 - * NULL.\r
 577 - */\r
 578  func (self *Messages) Get() *Message {\r
 579         if self.messages == nil {\r
 580                 return nil\r
 581 @@ -610,16 +425,6 @@ func (self *Messages) Get() *Message {\r
 582         return &Message{message: msg}\r
 583  }\r
 584  \r
 585 -/* Move the 'messages' iterator to the next message.\r
 586 - *\r
 587 - * If 'messages' is already pointing at the last message then the\r
 588 - * iterator will be moved to a point just beyond that last message,\r
 589 - * (where notmuch_messages_valid will return FALSE and\r
 590 - * notmuch_messages_get will return NULL).\r
 591 - *\r
 592 - * See the documentation of notmuch_query_search_messages for example\r
 593 - * code showing how to iterate over a notmuch_messages_t object.\r
 594 - */\r
 595  func (self *Messages) MoveToNext() {\r
 596         if self.messages == nil {\r
 597                 return\r
 598 @@ -627,30 +432,21 @@ func (self *Messages) MoveToNext() {\r
 599         C.notmuch_messages_move_to_next(self.messages)\r
 600  }\r
 601  \r
 602 -/* Destroy a notmuch_messages_t object.\r
 603 - *\r
 604 - * It's not strictly necessary to call this function. All memory from\r
 605 - * the notmuch_messages_t object will be reclaimed when the containing\r
 606 - * query object is destroyed.\r
 607 - */\r
 608  func (self *Messages) Destroy() {\r
 609         if self.messages != nil {\r
 610                 C.notmuch_messages_destroy(self.messages)\r
 611         }\r
 612  }\r
 613  \r
 614 -/* Return a list of tags from all messages.\r
 615 - *\r
 616 - * The resulting list is guaranteed not to contain duplicated tags.\r
 617 - *\r
 618 - * WARNING: You can no longer iterate over messages after calling this\r
 619 - * function, because the iterator will point at the end of the list.\r
 620 - * We do not have a function to reset the iterator yet and the only\r
 621 - * way how you can iterate over the list again is to recreate the\r
 622 - * message list.\r
 623 - *\r
 624 - * The function returns NULL on error.\r
 625 - */\r
 626 +// Return a list of tags from all messages.\r
 627 +//\r
 628 +// The resulting list is guaranteed not to contain duplicated tags.\r
 629 +//\r
 630 +// WARNING: You can no longer iterate over messages after calling this\r
 631 +// function, because the iterator will point at the end of the list.\r
 632 +// We do not have a function to reset the iterator yet and the only\r
 633 +// way how you can iterate over the list again is to recreate the\r
 634 +// message list.\r
 635  func (self *Messages) CollectTags() *Tags {\r
 636         if self.messages == nil {\r
 637                 return nil\r
 638 @@ -662,17 +458,16 @@ func (self *Messages) CollectTags() *Tags {\r
 639         return &Tags{tags: tags}\r
 640  }\r
 641  \r
 642 -/* Get the message ID of 'message'.\r
 643 - *\r
 644 - * The returned string belongs to 'message' and as such, should not be\r
 645 - * modified by the caller and will only be valid for as long as the\r
 646 - * message is valid, (which is until the query from which it derived\r
 647 - * is destroyed).\r
 648 - *\r
 649 - * This function will not return NULL since Notmuch ensures that every\r
 650 - * message has a unique message ID, (Notmuch will generate an ID for a\r
 651 - * message if the original file does not contain one).\r
 652 - */\r
 653 +// Get the message ID of 'message'.\r
 654 +//\r
 655 +// The returned string belongs to 'message' and as such, should not be\r
 656 +// modified by the caller and will only be valid for as long as the\r
 657 +// message is valid, (which is until the query from which it derived\r
 658 +// is destroyed).\r
 659 +//\r
 660 +// Notmuch ensures that every message has a unique message ID,\r
 661 +// (Notmuch will generate an ID for a message if the original file\r
 662 +// does not contain one).\r
 663  func (self *Message) GetMessageId() string {\r
 664  \r
 665         if self.message == nil {\r
 666 @@ -687,17 +482,7 @@ func (self *Message) GetMessageId() string {\r
 667         return C.GoString(id)\r
 668  }\r
 669  \r
 670 -/* Get the thread ID of 'message'.\r
 671 - *\r
 672 - * The returned string belongs to 'message' and as such, should not be\r
 673 - * modified by the caller and will only be valid for as long as the\r
 674 - * message is valid, (for example, until the user calls\r
 675 - * notmuch_message_destroy on 'message' or until a query from which it\r
 676 - * derived is destroyed).\r
 677 - *\r
 678 - * This function will not return NULL since Notmuch ensures that every\r
 679 - * message belongs to a single thread.\r
 680 - */\r
 681 +// Get the thread ID of 'message'. See GetMessageId().\r
 682  func (self *Message) GetThreadId() string {\r
 683  \r
 684         if self.message == nil {\r
 685 @@ -714,23 +499,9 @@ func (self *Message) GetThreadId() string {\r
 686         return C.GoString(id)\r
 687  }\r
 688  \r
 689 -/* Get a notmuch_messages_t iterator for all of the replies to\r
 690 - * 'message'.\r
 691 - *\r
 692 - * Note: This call only makes sense if 'message' was ultimately\r
 693 - * obtained from a notmuch_thread_t object, (such as by coming\r
 694 - * directly from the result of calling notmuch_thread_get_\r
 695 - * toplevel_messages or by any number of subsequent\r
 696 - * calls to notmuch_message_get_replies).\r
 697 - *\r
 698 - * If 'message' was obtained through some non-thread means, (such as\r
 699 - * by a call to notmuch_query_search_messages), then this function\r
 700 - * will return NULL.\r
 701 - *\r
 702 - * If there are no replies to 'message', this function will return\r
 703 - * NULL. (Note that notmuch_messages_valid will accept that NULL\r
 704 - * value as legitimate, and simply return FALSE for it.)\r
 705 - */\r
 706 +// Returns an *Messages object for all replies to the given message.\r
 707 +// Note: This call only makes sense if the message was obtained from a\r
 708 +// query for threads.\r
 709  func (self *Message) GetReplies() *Messages {\r
 710         if self.message == nil {\r
 711                 return nil\r
 712 @@ -742,20 +513,9 @@ func (self *Message) GetReplies() *Messages {\r
 713         return &Messages{messages: msgs}\r
 714  }\r
 715  \r
 716 -/* Get a filename for the email corresponding to 'message'.\r
 717 - *\r
 718 - * The returned filename is an absolute filename, (the initial\r
 719 - * component will match notmuch_database_get_path() ).\r
 720 - *\r
 721 - * The returned string belongs to the message so should not be\r
 722 - * modified or freed by the caller (nor should it be referenced after\r
 723 - * the message is destroyed).\r
 724 - *\r
 725 - * Note: If this message corresponds to multiple files in the mail\r
 726 - * store, (that is, multiple files contain identical message IDs),\r
 727 - * this function will arbitrarily return a single one of those\r
 728 - * filenames.\r
 729 - */\r
 730 +// Return the filename for the email corresponding to the message.\r
 731 +// The returned filename is an absolute filename, (the initial\r
 732 +// component will match notmuch_database_get_path() ).\r
 733  func (self *Message) GetFileName() string {\r
 734         if self.message == nil {\r
 735                 return ""\r
 736 @@ -777,7 +537,6 @@ const (\r
 737         MESSAGE_FLAG_MATCH Flag = 0\r
 738  )\r
 739  \r
 740 -/* Get a value of a flag for the email corresponding to 'message'. */\r
 741  func (self *Message) GetFlag(flag Flag) bool {\r
 742         if self.message == nil {\r
 743                 return false\r
 744 @@ -789,7 +548,6 @@ func (self *Message) GetFlag(flag Flag) bool {\r
 745         return true\r
 746  }\r
 747  \r
 748 -/* Set a value of a flag for the email corresponding to 'message'. */\r
 749  func (self *Message) SetFlag(flag Flag, value bool) {\r
 750         if self.message == nil {\r
 751                 return\r
 752 @@ -803,18 +561,12 @@ func (self *Message) SetFlag(flag Flag, value bool) {\r
 753  \r
 754  // TODO: wrap notmuch_message_get_date\r
 755  \r
 756 -/* Get the value of the specified header from 'message'.\r
 757 - *\r
 758 - * The value will be read from the actual message file, not from the\r
 759 - * notmuch database. The header name is case insensitive.\r
 760 - *\r
 761 - * The returned string belongs to the message so should not be\r
 762 - * modified or freed by the caller (nor should it be referenced after\r
 763 - * the message is destroyed).\r
 764 - *\r
 765 - * Returns an empty string ("") if the message does not contain a\r
 766 - * header line matching 'header'. Returns NULL if any error occurs.\r
 767 - */\r
 768 +// Get the value of the specified header from the message. The value\r
 769 +// will be read from the actual message file, not from the notmuch\r
 770 +// database. The header name is case insensitive.\r
 771 +//\r
 772 +// Returns an empty string ("") if the message does not contain a\r
 773 +// header line matching 'header' or an error occured.\r
 774  func (self *Message) GetHeader(header string) string {\r
 775         if self.message == nil {\r
 776                 return ""\r
 777 @@ -832,36 +584,8 @@ func (self *Message) GetHeader(header string) string {\r
 778         return C.GoString(value)\r
 779  }\r
 780  \r
 781 -/* Get the tags for 'message', returning a notmuch_tags_t object which\r
 782 - * can be used to iterate over all tags.\r
 783 - *\r
 784 - * The tags object is owned by the message and as such, will only be\r
 785 - * valid for as long as the message is valid, (which is until the\r
 786 - * query from which it derived is destroyed).\r
 787 - *\r
 788 - * Typical usage might be:\r
 789 - *\r
 790 - *     notmuch_message_t *message;\r
 791 - *     notmuch_tags_t *tags;\r
 792 - *     const char *tag;\r
 793 - *\r
 794 - *     message = notmuch_database_find_message (database, message_id);\r
 795 - *\r
 796 - *     for (tags = notmuch_message_get_tags (message);\r
 797 - *          notmuch_tags_valid (tags);\r
 798 - *          notmuch_result_move_to_next (tags))\r
 799 - *     {\r
 800 - *         tag = notmuch_tags_get (tags);\r
 801 - *         ....\r
 802 - *     }\r
 803 - *\r
 804 - *     notmuch_message_destroy (message);\r
 805 - *\r
 806 - * Note that there's no explicit destructor needed for the\r
 807 - * notmuch_tags_t object. (For consistency, we do provide a\r
 808 - * notmuch_tags_destroy function, but there's no good reason to call\r
 809 - * it if the message is about to be destroyed).\r
 810 - */\r
 811 +// Get the tags for 'message', returning a *Tags object which\r
 812 +// can be used to iterate over all tags. See SearchThreads().\r
 813  func (self *Message) GetTags() *Tags {\r
 814         if self.message == nil {\r
 815                 return nil\r
 816 @@ -876,20 +600,19 @@ func (self *Message) GetTags() *Tags {\r
 817  /* The longest possible tag value. */\r
 818  const TAG_MAX = 200\r
 819  \r
 820 -/* Add a tag to the given message.\r
 821 - *\r
 822 - * Return value:\r
 823 - *\r
 824 - * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message\r
 825 - *\r
 826 - * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL\r
 827 - *\r
 828 - * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long\r
 829 - *     (exceeds NOTMUCH_TAG_MAX)\r
 830 - *\r
 831 - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 832 - *     mode so message cannot be modified.\r
 833 - */\r
 834 +// Add a tag to the given message.\r
 835 +//\r
 836 +// Return value:\r
 837 +//\r
 838 +// NOTMUCH_STATUS_SUCCESS: Tag successfully added to message\r
 839 +//\r
 840 +// NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL\r
 841 +//\r
 842 +// NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long\r
 843 +// (exceeds NOTMUCH_TAG_MAX)\r
 844 +//\r
 845 +// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 846 +// mode so message cannot be modified.\r
 847  func (self *Message) AddTag(tag string) Status {\r
 848         if self.message == nil {\r
 849                 return STATUS_NULL_POINTER\r
 850 @@ -900,20 +623,6 @@ func (self *Message) AddTag(tag string) Status {\r
 851         return Status(C.notmuch_message_add_tag(self.message, c_tag))\r
 852  }\r
 853  \r
 854 -/* Remove a tag from the given message.\r
 855 - *\r
 856 - * Return value:\r
 857 - *\r
 858 - * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message\r
 859 - *\r
 860 - * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL\r
 861 - *\r
 862 - * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long\r
 863 - *     (exceeds NOTMUCH_TAG_MAX)\r
 864 - *\r
 865 - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 866 - *     mode so message cannot be modified.\r
 867 - */\r
 868  func (self *Message) RemoveTag(tag string) Status {\r
 869         if self.message == nil {\r
 870                 return STATUS_NULL_POINTER\r
 871 @@ -924,14 +633,6 @@ func (self *Message) RemoveTag(tag string) Status {\r
 872         return Status(C.notmuch_message_remove_tag(self.message, c_tag))\r
 873  }\r
 874  \r
 875 -/* Remove all tags from the given message.\r
 876 - *\r
 877 - * See notmuch_message_freeze for an example showing how to safely\r
 878 - * replace tag values.\r
 879 - *\r
 880 - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 881 - *     mode so message cannot be modified.\r
 882 - */\r
 883  func (self *Message) RemoveAllTags() Status {\r
 884         if self.message == nil {\r
 885                 return STATUS_NULL_POINTER\r
 886 @@ -939,46 +640,44 @@ func (self *Message) RemoveAllTags() Status {\r
 887         return Status(C.notmuch_message_remove_all_tags(self.message))\r
 888  }\r
 889  \r
 890 -/* Freeze the current state of 'message' within the database.\r
 891 - *\r
 892 - * This means that changes to the message state, (via\r
 893 - * notmuch_message_add_tag, notmuch_message_remove_tag, and\r
 894 - * notmuch_message_remove_all_tags), will not be committed to the\r
 895 - * database until the message is thawed with notmuch_message_thaw.\r
 896 - *\r
 897 - * Multiple calls to freeze/thaw are valid and these calls will\r
 898 - * "stack". That is there must be as many calls to thaw as to freeze\r
 899 - * before a message is actually thawed.\r
 900 - *\r
 901 - * The ability to do freeze/thaw allows for safe transactions to\r
 902 - * change tag values. For example, explicitly setting a message to\r
 903 - * have a given set of tags might look like this:\r
 904 - *\r
 905 - *    notmuch_message_freeze (message);\r
 906 - *\r
 907 - *    notmuch_message_remove_all_tags (message);\r
 908 - *\r
 909 - *    for (i = 0; i < NUM_TAGS; i++)\r
 910 - *        notmuch_message_add_tag (message, tags[i]);\r
 911 - *\r
 912 - *    notmuch_message_thaw (message);\r
 913 - *\r
 914 - * With freeze/thaw used like this, the message in the database is\r
 915 - * guaranteed to have either the full set of original tag values, or\r
 916 - * the full set of new tag values, but nothing in between.\r
 917 - *\r
 918 - * Imagine the example above without freeze/thaw and the operation\r
 919 - * somehow getting interrupted. This could result in the message being\r
 920 - * left with no tags if the interruption happened after\r
 921 - * notmuch_message_remove_all_tags but before notmuch_message_add_tag.\r
 922 - *\r
 923 - * Return value:\r
 924 - *\r
 925 - * NOTMUCH_STATUS_SUCCESS: Message successfully frozen.\r
 926 - *\r
 927 - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 928 - *     mode so message cannot be modified.\r
 929 - */\r
 930 +// Freeze the current state of the message within the database.\r
 931 +//\r
 932 +// This means that changes to the message state will not be committed\r
 933 +// to the database until the message is thawed with Thaw().\r
 934 +//\r
 935 +// Multiple calls to freeze/thaw are valid and these calls will\r
 936 +// "stack". That is there must be as many calls to thaw as to freeze\r
 937 +// before a message is actually thawed.\r
 938 +//\r
 939 +// The ability to do freeze/thaw allows for safe transactions to\r
 940 +// change tag values. For example, explicitly setting a message to\r
 941 +// have a given set of tags might look like this:\r
 942 +//\r
 943 +//    notmuch_message_freeze (message);\r
 944 +//\r
 945 +//    notmuch_message_remove_all_tags (message);\r
 946 +//\r
 947 +//    for (i = 0; i < NUM_TAGS; i++)\r
 948 +//        notmuch_message_add_tag (message, tags[i]);\r
 949 +//\r
 950 +//    notmuch_message_thaw (message);\r
 951 +//\r
 952 +// With freeze/thaw used like this, the message in the database is\r
 953 +// guaranteed to have either the full set of original tag values, or\r
 954 +// the full set of new tag values, but nothing in between.\r
 955 +//\r
 956 +// Imagine the example above without freeze/thaw and the operation\r
 957 +// somehow getting interrupted. This could result in the message being\r
 958 +// left with no tags if the interruption happened after\r
 959 +// notmuch_message_remove_all_tags but before notmuch_message_add_tag.\r
 960 +//\r
 961 +// Return value:\r
 962 +//\r
 963 +// NOTMUCH_STATUS_SUCCESS: Message successfully frozen.\r
 964 +//\r
 965 +// NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only\r
 966 +// mode so message cannot be modified.\r
 967 +///\r
 968  func (self *Message) Freeze() Status {\r
 969         if self.message == nil {\r
 970                 return STATUS_NULL_POINTER\r
 971 @@ -986,26 +685,8 @@ func (self *Message) Freeze() Status {\r
 972         return Status(C.notmuch_message_freeze(self.message))\r
 973  }\r
 974  \r
 975 -/* Thaw the current 'message', synchronizing any changes that may have\r
 976 - * occurred while 'message' was frozen into the notmuch database.\r
 977 - *\r
 978 - * See notmuch_message_freeze for an example of how to use this\r
 979 - * function to safely provide tag changes.\r
 980 - *\r
 981 - * Multiple calls to freeze/thaw are valid and these calls with\r
 982 - * "stack". That is there must be as many calls to thaw as to freeze\r
 983 - * before a message is actually thawed.\r
 984 - *\r
 985 - * Return value:\r
 986 - *\r
 987 - * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least\r
 988 - *     its frozen count has successfully been reduced by 1).\r
 989 - *\r
 990 - * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw\r
 991 - *     an unfrozen message. That is, there have been an unbalanced\r
 992 - *     number of calls to notmuch_message_freeze and\r
 993 - *     notmuch_message_thaw.\r
 994 - */\r
 995 +// Thaw the current 'message', synchronizing any changes that may have\r
 996 +// occurred while 'message' was frozen into the notmuch database.\r
 997  func (self *Message) Thaw() Status {\r
 998         if self.message == nil {\r
 999                 return STATUS_NULL_POINTER\r
1000 @@ -1014,14 +695,13 @@ func (self *Message) Thaw() Status {\r
1001         return Status(C.notmuch_message_thaw(self.message))\r
1002  }\r
1003  \r
1004 -/* Destroy a notmuch_message_t object.\r
1005 - *\r
1006 - * It can be useful to call this function in the case of a single\r
1007 - * query object with many messages in the result, (such as iterating\r
1008 - * over the entire database). Otherwise, it's fine to never call this\r
1009 - * function and there will still be no memory leaks. (The memory from\r
1010 - * the messages get reclaimed when the containing query is destroyed.)\r
1011 - */\r
1012 +// Destroy a notmuch_message_t object.\r
1013 +//\r
1014 +// It can be useful to call this function in the case of a single\r
1015 +// query object with many messages in the result, (such as iterating\r
1016 +// over the entire database). Otherwise, it's fine to never call this\r
1017 +// function and there will still be no memory leaks. (The memory from\r
1018 +// the messages get reclaimed when the containing query is destroyed.)\r
1019  func (self *Message) Destroy() {\r
1020         if self.message == nil {\r
1021                 return\r
1022 @@ -1029,15 +709,6 @@ func (self *Message) Destroy() {\r
1023         C.notmuch_message_destroy(self.message)\r
1024  }\r
1025  \r
1026 -/* Is the given 'tags' iterator pointing at a valid tag.\r
1027 - *\r
1028 - * When this function returns TRUE, notmuch_tags_get will return a\r
1029 - * valid string. Whereas when this function returns FALSE,\r
1030 - * notmuch_tags_get will return NULL.\r
1031 - *\r
1032 - * See the documentation of notmuch_message_get_tags for example code\r
1033 - * showing how to iterate over a notmuch_tags_t object.\r
1034 - */\r
1035  func (self *Tags) Valid() bool {\r
1036         if self.tags == nil {\r
1037                 return false\r
1038 @@ -1049,14 +720,6 @@ func (self *Tags) Valid() bool {\r
1039         return true\r
1040  }\r
1041  \r
1042 -/* Get the current tag from 'tags' as a string.\r
1043 - *\r
1044 - * Note: The returned string belongs to 'tags' and has a lifetime\r
1045 - * identical to it (and the query to which it ultimately belongs).\r
1046 - *\r
1047 - * See the documentation of notmuch_message_get_tags for example code\r
1048 - * showing how to iterate over a notmuch_tags_t object.\r
1049 - */\r
1050  func (self *Tags) Get() string {\r
1051         if self.tags == nil {\r
1052                 return ""\r
1053 @@ -1066,20 +729,11 @@ func (self *Tags) Get() string {\r
1054  \r
1055         return C.GoString(s)\r
1056  }\r
1057 +\r
1058  func (self *Tags) String() string {\r
1059         return self.Get()\r
1060  }\r
1061  \r
1062 -/* Move the 'tags' iterator to the next tag.\r
1063 - *\r
1064 - * If 'tags' is already pointing at the last tag then the iterator\r
1065 - * will be moved to a point just beyond that last tag, (where\r
1066 - * notmuch_tags_valid will return FALSE and notmuch_tags_get will\r
1067 - * return NULL).\r
1068 - *\r
1069 - * See the documentation of notmuch_message_get_tags for example code\r
1070 - * showing how to iterate over a notmuch_tags_t object.\r
1071 - */\r
1072  func (self *Tags) MoveToNext() {\r
1073         if self.tags == nil {\r
1074                 return\r
1075 @@ -1087,12 +741,6 @@ func (self *Tags) MoveToNext() {\r
1076         C.notmuch_tags_move_to_next(self.tags)\r
1077  }\r
1078  \r
1079 -/* Destroy a notmuch_tags_t object.\r
1080 - *\r
1081 - * It's not strictly necessary to call this function. All memory from\r
1082 - * the notmuch_tags_t object will be reclaimed when the containing\r
1083 - * message or query objects are destroyed.\r
1084 - */\r
1085  func (self *Tags) Destroy() {\r
1086         if self.tags == nil {\r
1087                 return\r
1088 @@ -1102,7 +750,7 @@ func (self *Tags) Destroy() {\r
1089  \r
1090  // TODO: wrap notmuch_directory_<fct>\r
1091  \r
1092 -/* Destroy a notmuch_directory_t object. */\r
1093 +// Destroy a notmuch_directory_t object.\r
1094  func (self *Directory) Destroy() {\r
1095         if self.dir == nil {\r
1096                 return\r
1097 @@ -1112,15 +760,6 @@ func (self *Directory) Destroy() {\r
1098  \r
1099  // TODO: wrap notmuch_filenames_<fct>\r
1100  \r
1101 -/* Destroy a notmuch_filenames_t object.\r
1102 - *\r
1103 - * It's not strictly necessary to call this function. All memory from\r
1104 - * the notmuch_filenames_t object will be reclaimed when the\r
1105 - * containing directory object is destroyed.\r
1106 - *\r
1107 - * It is acceptable to pass NULL for 'filenames', in which case this\r
1108 - * function will do nothing.\r
1109 - */\r
1110  func (self *Filenames) Destroy() {\r
1111         if self.fnames == nil {\r
1112                 return\r
1113 -- \r
1114 1.7.10.4\r
1115 \r