d8/9c4fa115b71d353dd3f41edfbcb283c459dd25

   1 Return-Path: <tomi.ollila@iki.fi>\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 171C4431FC0\r
   6         for <notmuch@notmuchmail.org>; Wed,  1 Jan 2014 07:00:16 -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 I59gL82poopI for <notmuch@notmuchmail.org>;\r
  16         Wed,  1 Jan 2014 07:00:11 -0800 (PST)\r
  17 Received: from guru.guru-group.fi (guru.guru-group.fi [46.183.73.34])\r
  18         by olra.theworths.org (Postfix) with ESMTP id 84D20431FAF\r
  19         for <notmuch@notmuchmail.org>; Wed,  1 Jan 2014 07:00:10 -0800 (PST)\r
  20 Received: from guru.guru-group.fi (localhost [IPv6:::1])\r
  21         by guru.guru-group.fi (Postfix) with ESMTP id ED8831000B2;\r
  22         Wed,  1 Jan 2014 17:00:04 +0200 (EET)\r
  23 From: Tomi Ollila <tomi.ollila@iki.fi>\r
  24 To: Jani Nikula <jani@nikula.org>, notmuch@notmuchmail.org\r
  25 Subject: Re: [PATCH 2/2] lib: modify notmuch.h for automatic document\r
  26         generation\r
  27 In-Reply-To:\r
  28  <8900d3fb7b01b8b97f35deb8030affea32d50fe9.1385826040.git.jani@nikula.org>\r
  29 References: <cover.1385826040.git.jani@nikula.org>\r
  30         <8900d3fb7b01b8b97f35deb8030affea32d50fe9.1385826040.git.jani@nikula.org>\r
  31 User-Agent: Notmuch/0.17+13~gdfcf116 (http://notmuchmail.org) Emacs/24.3.1\r
  32         (x86_64-unknown-linux-gnu)\r
  33 X-Face: HhBM'cA~<r"^Xv\KRN0P{vn'Y"Kd;zg_y3S[4)KSN~s?O\"QPoL\r
  34         $[Xv_BD:i/F$WiEWax}R(MPS`^UaptOGD`*/=@\1lKoVa9tnrg0TW?"r7aRtgk[F\r
  35         !)g;OY^,BjTbr)Np:%c_o'jj,Z\r
  36 Date: Wed, 01 Jan 2014 17:00:04 +0200\r
  37 Message-ID: <m2wqijoih7.fsf@guru.guru-group.fi>\r
  38 MIME-Version: 1.0\r
  39 Content-Type: text/plain\r
  40 X-BeenThere: notmuch@notmuchmail.org\r
  41 X-Mailman-Version: 2.1.13\r
  42 Precedence: list\r
  43 List-Id: "Use and development of the notmuch mail system."\r
  44         <notmuch.notmuchmail.org>\r
  45 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  46         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  47 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  48 List-Post: <mailto:notmuch@notmuchmail.org>\r
  49 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  50 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  51         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  52 X-List-Received-Date: Wed, 01 Jan 2014 15:00:16 -0000\r
  53 \r
  54 On Sat, Nov 30 2013, Jani Nikula <jani@nikula.org> wrote:\r
  55 \r
  56 > Minimal changes to produce a sensible result.\r
  57 > ---\r
  58 \r
  59 Looks good but does not apply anymore (blame Austin)\r
  60 Also the doxygen -s -g (+ edits) looks good ;D\r
  61 \r
  62 Tomi\r
  63 \r
  64 \r
  65 >  lib/notmuch.h | 436 +++++++++++++++++++++++++++++++++++++++-------------------\r
  66 >  1 file changed, 296 insertions(+), 140 deletions(-)\r
  67 >\r
  68 > diff --git a/lib/notmuch.h b/lib/notmuch.h\r
  69 > index 7c3a30c..708b603 100644\r
  70 > --- a/lib/notmuch.h\r
  71 > +++ b/lib/notmuch.h\r
  72 > @@ -18,9 +18,19 @@\r
  73 >   * Author: Carl Worth <cworth@cworth.org>\r
  74 >   */\r
  75 >  \r
  76 > +/**\r
  77 > + * @defgroup notmuch The notmuch API\r
  78 > + *\r
  79 > + * Not much of an email library, (just index and search)\r
  80 > + *\r
  81 > + * @{\r
  82 > + */\r
  83 > +\r
  84 >  #ifndef NOTMUCH_H\r
  85 >  #define NOTMUCH_H\r
  86 >  \r
  87 > +#ifndef __DOXYGEN__\r
  88 > +\r
  89 >  #ifdef  __cplusplus\r
  90 >  # define NOTMUCH_BEGIN_DECLS  extern "C" {\r
  91 >  # define NOTMUCH_END_DECLS    }\r
  92 > @@ -45,18 +55,20 @@ NOTMUCH_BEGIN_DECLS\r
  93 >  #define NOTMUCH_MINOR_VERSION        17\r
  94 >  #define NOTMUCH_MICRO_VERSION        0\r
  95 >  \r
  96 > -/*\r
  97 > +#endif /* __DOXYGEN__ */\r
  98 > +\r
  99 > +/**\r
 100 >   * Check the version of the notmuch library being compiled against.\r
 101 >   *\r
 102 >   * Return true if the library being compiled against is of the\r
 103 >   * specified version or above. For example:\r
 104 >   *\r
 105 > - * #if NOTMUCH_CHECK_VERSION(0, 18, 0)\r
 106 > + * \#if NOTMUCH_CHECK_VERSION(0, 18, 0)\r
 107 >   *     (code requiring notmuch 0.18 or above)\r
 108 > - * #endif\r
 109 > + * \#endif\r
 110 >   *\r
 111 >   * NOTMUCH_CHECK_VERSION has been defined since version 0.17.0; you\r
 112 > - * can use #if !defined(NOTMUCH_CHECK_VERSION) to check for versions\r
 113 > + * can use \#if !defined(NOTMUCH_CHECK_VERSION) to check for versions\r
 114 >   * prior to that.\r
 115 >   */\r
 116 >  #define NOTMUCH_CHECK_VERSION (major, minor, micro)                  \\r
 117 > @@ -65,80 +77,97 @@ NOTMUCH_BEGIN_DECLS\r
 118 >       (NOTMUCH_MAJOR_VERSION == (major) && NOTMUCH_MINOR_VERSION == (minor) && \\r
 119 >        NOTMUCH_MICRO_VERSION >= (micro)))\r
 120 >  \r
 121 > +/**\r
 122 > + * Notmuch boolean type.\r
 123 > + */\r
 124 >  typedef int notmuch_bool_t;\r
 125 >  \r
 126 > -/* Status codes used for the return values of most functions.\r
 127 > +/**\r
 128 > + * Status codes used for the return values of most functions.\r
 129 >   *\r
 130 >   * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function\r
 131 > - * completed without error. Any other value indicates an error as\r
 132 > - * follows:\r
 133 > - *\r
 134 > - * NOTMUCH_STATUS_SUCCESS: No error occurred.\r
 135 > - *\r
 136 > - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory\r
 137 > - *\r
 138 > - * XXX: We don't really want to expose this lame XAPIAN_EXCEPTION\r
 139 > - * value. Instead we should map to things like DATABASE_LOCKED or\r
 140 > - * whatever.\r
 141 > - *\r
 142 > - * NOTMUCH_STATUS_READ_ONLY_DATABASE: An attempt was made to write to\r
 143 > - *   a database opened in read-only mode.\r
 144 > + * completed without error. Any other value indicates an error.\r
 145 >   *\r
 146 > - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred\r
 147 > - *\r
 148 > - * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to read or\r
 149 > - *   write to a file (this could be file not found, permission\r
 150 > - *   denied, etc.)\r
 151 > - *\r
 152 > - * NOTMUCH_STATUS_FILE_NOT_EMAIL: A file was presented that doesn't\r
 153 > - *   appear to be an email message.\r
 154 > - *\r
 155 > - * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: A file contains a message ID\r
 156 > - *   that is identical to a message already in the database.\r
 157 > - *\r
 158 > - * NOTMUCH_STATUS_NULL_POINTER: The user erroneously passed a NULL\r
 159 > - *   pointer to a notmuch function.\r
 160 > - *\r
 161 > - * NOTMUCH_STATUS_TAG_TOO_LONG: A tag value is too long (exceeds\r
 162 > - *   NOTMUCH_TAG_MAX)\r
 163 > - *\r
 164 > - * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: The notmuch_message_thaw\r
 165 > - *   function has been called more times than notmuch_message_freeze.\r
 166 > - *\r
 167 > - * NOTMUCH_STATUS_UNBALANCED_ATOMIC: notmuch_database_end_atomic has\r
 168 > - *   been called more times than notmuch_database_begin_atomic.\r
 169 > - *\r
 170 > - * And finally:\r
 171 > - *\r
 172 > - * NOTMUCH_STATUS_LAST_STATUS: Not an actual status value. Just a way\r
 173 > - *   to find out how many valid status values there are.\r
 174 >   */\r
 175 >  typedef enum _notmuch_status {\r
 176 > +    /**\r
 177 > +     * No error occurred.\r
 178 > +     */\r
 179 >      NOTMUCH_STATUS_SUCCESS = 0,\r
 180 > +    /**\r
 181 > +     * Out of memory.\r
 182 > +     */\r
 183 >      NOTMUCH_STATUS_OUT_OF_MEMORY,\r
 184 > +    /**\r
 185 > +     * An attempt was made to write to a database opened in read-only\r
 186 > +     * mode.\r
 187 > +     */\r
 188 >      NOTMUCH_STATUS_READ_ONLY_DATABASE,\r
 189 > +    /**\r
 190 > +     * A Xapian exception occurred.\r
 191 > +     */\r
 192 >      NOTMUCH_STATUS_XAPIAN_EXCEPTION,\r
 193 > +    /**\r
 194 > +     * An error occurred trying to read or write to a file (this could\r
 195 > +     * be file not found, permission denied, etc.)\r
 196 > +     *\r
 197 > +     * @todo We don't really want to expose this lame XAPIAN_EXCEPTION\r
 198 > +     * value. Instead we should map to things like DATABASE_LOCKED or\r
 199 > +     * whatever.\r
 200 > +     */\r
 201 >      NOTMUCH_STATUS_FILE_ERROR,\r
 202 > +    /**\r
 203 > +     * A file was presented that doesn't appear to be an email\r
 204 > +     * message.\r
 205 > +     */\r
 206 >      NOTMUCH_STATUS_FILE_NOT_EMAIL,\r
 207 > +    /**\r
 208 > +     * A file contains a message ID that is identical to a message\r
 209 > +     * already in the database.\r
 210 > +     */\r
 211 >      NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID,\r
 212 > +    /**\r
 213 > +     * The user erroneously passed a NULL pointer to a notmuch\r
 214 > +     * function.\r
 215 > +     */\r
 216 >      NOTMUCH_STATUS_NULL_POINTER,\r
 217 > +    /**\r
 218 > +     * A tag value is too long (exceeds NOTMUCH_TAG_MAX).\r
 219 > +     */\r
 220 >      NOTMUCH_STATUS_TAG_TOO_LONG,\r
 221 > +    /**\r
 222 > +     * The notmuch_message_thaw function has been called more times\r
 223 > +     * than notmuch_message_freeze.\r
 224 > +     */\r
 225 >      NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,\r
 226 > +    /**\r
 227 > +     * notmuch_database_end_atomic has been called more times than\r
 228 > +     * notmuch_database_begin_atomic.\r
 229 > +     */\r
 230 >      NOTMUCH_STATUS_UNBALANCED_ATOMIC,\r
 231 > +    /**\r
 232 > +     * The operation is not supported.\r
 233 > +     */\r
 234 >      NOTMUCH_STATUS_UNSUPPORTED_OPERATION,\r
 235 > -\r
 236 > +    /**\r
 237 > +     * Not an actual status value. Just a way to find out how many\r
 238 > +     * valid status values there are.\r
 239 > +     */\r
 240 >      NOTMUCH_STATUS_LAST_STATUS\r
 241 >  } notmuch_status_t;\r
 242 >  \r
 243 > -/* Get a string representation of a notmuch_status_t value.\r
 244 > +/**\r
 245 > + * Get a string representation of a notmuch_status_t value.\r
 246 >   *\r
 247 >   * The result is read-only.\r
 248 >   */\r
 249 >  const char *\r
 250 >  notmuch_status_to_string (notmuch_status_t status);\r
 251 >  \r
 252 > +\r
 253 >  /* Various opaque data types. For each notmuch_<foo>_t see the various\r
 254 >   * notmuch_<foo> functions below. */\r
 255 > +#ifndef __DOXYGEN__\r
 256 >  typedef struct _notmuch_database notmuch_database_t;\r
 257 >  typedef struct _notmuch_query notmuch_query_t;\r
 258 >  typedef struct _notmuch_threads notmuch_threads_t;\r
 259 > @@ -148,8 +177,10 @@ typedef struct _notmuch_message notmuch_message_t;\r
 260 >  typedef struct _notmuch_tags notmuch_tags_t;\r
 261 >  typedef struct _notmuch_directory notmuch_directory_t;\r
 262 >  typedef struct _notmuch_filenames notmuch_filenames_t;\r
 263 > +#endif /* __DOXYGEN__ */\r
 264 >  \r
 265 > -/* Create a new, empty notmuch database located at 'path'.\r
 266 > +/**\r
 267 > + * Create a new, empty notmuch database located at 'path'.\r
 268 >   *\r
 269 >   * The path should be a top-level directory to a collection of\r
 270 >   * plain-text email messages (one message per file). This call will\r
 271 > @@ -185,12 +216,22 @@ typedef struct _notmuch_filenames notmuch_filenames_t;\r
 272 >  notmuch_status_t\r
 273 >  notmuch_database_create (const char *path, notmuch_database_t **database);\r
 274 >  \r
 275 > +/**\r
 276 > + * Database open mode for notmuch_database_open.\r
 277 > + */\r
 278 >  typedef enum {\r
 279 > +    /**\r
 280 > +     * Open database for reading only.\r
 281 > +     */\r
 282 >      NOTMUCH_DATABASE_MODE_READ_ONLY = 0,\r
 283 > +    /**\r
 284 > +     * Open database for reading and writing.\r
 285 > +     */\r
 286 >      NOTMUCH_DATABASE_MODE_READ_WRITE\r
 287 >  } notmuch_database_mode_t;\r
 288 >  \r
 289 > -/* Open an existing notmuch database located at 'path'.\r
 290 > +/**\r
 291 > + * Open an existing notmuch database located at 'path'.\r
 292 >   *\r
 293 >   * The database should have been created at some time in the past,\r
 294 >   * (not necessarily by this process), by calling\r
 295 > @@ -226,7 +267,8 @@ notmuch_database_open (const char *path,\r
 296 >                      notmuch_database_mode_t mode,\r
 297 >                      notmuch_database_t **database);\r
 298 >  \r
 299 > -/* Close the given notmuch database.\r
 300 > +/**\r
 301 > + * Close the given notmuch database.\r
 302 >   *\r
 303 >   * After notmuch_database_close has been called, calls to other\r
 304 >   * functions on objects derived from this database may either behave\r
 305 > @@ -240,12 +282,14 @@ notmuch_database_open (const char *path,\r
 306 >  void\r
 307 >  notmuch_database_close (notmuch_database_t *database);\r
 308 >  \r
 309 > -/* A callback invoked by notmuch_database_compact to notify the user\r
 310 > +/**\r
 311 > + * A callback invoked by notmuch_database_compact to notify the user\r
 312 >   * of the progress of the compaction process.\r
 313 >   */\r
 314 >  typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure);\r
 315 >  \r
 316 > -/* Compact a notmuch database, backing up the original database to the\r
 317 > +/**\r
 318 > + * Compact a notmuch database, backing up the original database to the\r
 319 >   * given path.\r
 320 >   *\r
 321 >   * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE\r
 322 > @@ -261,33 +305,41 @@ notmuch_database_compact (const char* path,\r
 323 >                         notmuch_compact_status_cb_t status_cb,\r
 324 >                         void *closure);\r
 325 >  \r
 326 > -/* Destroy the notmuch database, closing it if necessary and freeing\r
 327 > +/**\r
 328 > + * Destroy the notmuch database, closing it if necessary and freeing\r
 329 >   * all associated resources.\r
 330 >   */\r
 331 >  void\r
 332 >  notmuch_database_destroy (notmuch_database_t *database);\r
 333 >  \r
 334 > -/* Return the database path of the given database.\r
 335 > +/**\r
 336 > + * Return the database path of the given database.\r
 337 >   *\r
 338 >   * The return value is a string owned by notmuch so should not be\r
 339 > - * modified nor freed by the caller. */\r
 340 > + * modified nor freed by the caller.\r
 341 > + */\r
 342 >  const char *\r
 343 >  notmuch_database_get_path (notmuch_database_t *database);\r
 344 >  \r
 345 > -/* Return the database format version of the given database. */\r
 346 > +/**\r
 347 > + * Return the database format version of the given database.\r
 348 > + */\r
 349 >  unsigned int\r
 350 >  notmuch_database_get_version (notmuch_database_t *database);\r
 351 >  \r
 352 > -/* Does this database need to be upgraded before writing to it?\r
 353 > +/**\r
 354 > + * Does this database need to be upgraded before writing to it?\r
 355 >   *\r
 356 >   * If this function returns TRUE then no functions that modify the\r
 357 >   * database (notmuch_database_add_message, notmuch_message_add_tag,\r
 358 >   * notmuch_directory_set_mtime, etc.) will work unless the function\r
 359 > - * notmuch_database_upgrade is called successfully first. */\r
 360 > + * notmuch_database_upgrade is called successfully first.\r
 361 > + */\r
 362 >  notmuch_bool_t\r
 363 >  notmuch_database_needs_upgrade (notmuch_database_t *database);\r
 364 >  \r
 365 > -/* Upgrade the current database.\r
 366 > +/**\r
 367 > + * Upgrade the current database.\r
 368 >   *\r
 369 >   * After opening a database in read-write mode, the client should\r
 370 >   * check if an upgrade is needed (notmuch_database_needs_upgrade) and\r
 371 > @@ -306,7 +358,8 @@ notmuch_database_upgrade (notmuch_database_t *database,\r
 372 >                                                  double progress),\r
 373 >                         void *closure);\r
 374 >  \r
 375 > -/* Begin an atomic database operation.\r
 376 > +/**\r
 377 > + * Begin an atomic database operation.\r
 378 >   *\r
 379 >   * Any modifications performed between a successful begin and a\r
 380 >   * notmuch_database_end_atomic will be applied to the database\r
 381 > @@ -327,7 +380,8 @@ notmuch_database_upgrade (notmuch_database_t *database,\r
 382 >  notmuch_status_t\r
 383 >  notmuch_database_begin_atomic (notmuch_database_t *notmuch);\r
 384 >  \r
 385 > -/* Indicate the end of an atomic database operation.\r
 386 > +/**\r
 387 > + * Indicate the end of an atomic database operation.\r
 388 >   *\r
 389 >   * Return value:\r
 390 >   *\r
 391 > @@ -342,7 +396,8 @@ notmuch_database_begin_atomic (notmuch_database_t *notmuch);\r
 392 >  notmuch_status_t\r
 393 >  notmuch_database_end_atomic (notmuch_database_t *notmuch);\r
 394 >  \r
 395 > -/* Retrieve a directory object from the database for 'path'.\r
 396 > +/**\r
 397 > + * Retrieve a directory object from the database for 'path'.\r
 398 >   *\r
 399 >   * Here, 'path' should be a path relative to the path of 'database'\r
 400 >   * (see notmuch_database_get_path), or else should be an absolute path\r
 401 > @@ -365,7 +420,8 @@ notmuch_database_get_directory (notmuch_database_t *database,\r
 402 >                               const char *path,\r
 403 >                               notmuch_directory_t **directory);\r
 404 >  \r
 405 > -/* Add a new message to the given notmuch database or associate an\r
 406 > +/**\r
 407 > + * Add a new message to the given notmuch database or associate an\r
 408 >   * additional filename with an existing message.\r
 409 >   *\r
 410 >   * Here, 'filename' should be a path relative to the path of\r
 411 > @@ -416,7 +472,8 @@ notmuch_database_add_message (notmuch_database_t *database,\r
 412 >                             const char *filename,\r
 413 >                             notmuch_message_t **message);\r
 414 >  \r
 415 > -/* Remove a message filename from the given notmuch database. If the\r
 416 > +/**\r
 417 > + * Remove a message filename from the given notmuch database. If the\r
 418 >   * message has no more filenames, remove the message.\r
 419 >   *\r
 420 >   * If the same message (as determined by the message ID) is still\r
 421 > @@ -444,7 +501,8 @@ notmuch_status_t\r
 422 >  notmuch_database_remove_message (notmuch_database_t *database,\r
 423 >                                const char *filename);\r
 424 >  \r
 425 > -/* Find a message with the given message_id.\r
 426 > +/**\r
 427 > + * Find a message with the given message_id.\r
 428 >   *\r
 429 >   * If a message with the given message_id is found then, on successful return\r
 430 >   * (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to a message\r
 431 > @@ -471,7 +529,8 @@ notmuch_database_find_message (notmuch_database_t *database,\r
 432 >                              const char *message_id,\r
 433 >                              notmuch_message_t **message);\r
 434 >  \r
 435 > -/* Find a message with the given filename.\r
 436 > +/**\r
 437 > + * Find a message with the given filename.\r
 438 >   *\r
 439 >   * If the database contains a message with the given filename then, on\r
 440 >   * successful return (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to\r
 441 > @@ -498,7 +557,8 @@ notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,\r
 442 >                                          const char *filename,\r
 443 >                                          notmuch_message_t **message);\r
 444 >  \r
 445 > -/* Return a list of all tags found in the database.\r
 446 > +/**\r
 447 > + * Return a list of all tags found in the database.\r
 448 >   *\r
 449 >   * This function creates a list of all tags found in the database. The\r
 450 >   * resulting list contains all tags from all messages found in the database.\r
 451 > @@ -508,7 +568,8 @@ notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,\r
 452 >  notmuch_tags_t *\r
 453 >  notmuch_database_get_all_tags (notmuch_database_t *db);\r
 454 >  \r
 455 > -/* Create a new query for 'database'.\r
 456 > +/**\r
 457 > + * Create a new query for 'database'.\r
 458 >   *\r
 459 >   * Here, 'database' should be an open database, (see\r
 460 >   * notmuch_database_open and notmuch_database_create).\r
 461 > @@ -536,19 +597,36 @@ notmuch_query_t *\r
 462 >  notmuch_query_create (notmuch_database_t *database,\r
 463 >                     const char *query_string);\r
 464 >  \r
 465 > -/* Sort values for notmuch_query_set_sort */\r
 466 > +/**\r
 467 > + * Sort values for notmuch_query_set_sort.\r
 468 > + */\r
 469 >  typedef enum {\r
 470 > +    /**\r
 471 > +     * Oldest first.\r
 472 > +     */\r
 473 >      NOTMUCH_SORT_OLDEST_FIRST,\r
 474 > +    /**\r
 475 > +     * Newest first.\r
 476 > +     */\r
 477 >      NOTMUCH_SORT_NEWEST_FIRST,\r
 478 > +    /**\r
 479 > +     * Sort by message-id.\r
 480 > +     */\r
 481 >      NOTMUCH_SORT_MESSAGE_ID,\r
 482 > +    /**\r
 483 > +     * Do not sort.\r
 484 > +     */\r
 485 >      NOTMUCH_SORT_UNSORTED\r
 486 >  } notmuch_sort_t;\r
 487 >  \r
 488 > -/* Return the query_string of this query. See notmuch_query_create. */\r
 489 > +/**\r
 490 > + * Return the query_string of this query. See notmuch_query_create.\r
 491 > + */\r
 492 >  const char *\r
 493 >  notmuch_query_get_query_string (notmuch_query_t *query);\r
 494 >  \r
 495 > -/* Exclude values for notmuch_query_set_omit_excluded. The strange\r
 496 > +/**\r
 497 > + * Exclude values for notmuch_query_set_omit_excluded. The strange\r
 498 >   * order is to maintain backward compatibility: the old FALSE/TRUE\r
 499 >   * options correspond to the new\r
 500 >   * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.\r
 501 > @@ -560,7 +638,8 @@ typedef enum {\r
 502 >      NOTMUCH_EXCLUDE_ALL\r
 503 >  } notmuch_exclude_t;\r
 504 >  \r
 505 > -/* Specify whether to omit excluded results or simply flag them.  By\r
 506 > +/**\r
 507 > + * Specify whether to omit excluded results or simply flag them.  By\r
 508 >   * default, this is set to TRUE.\r
 509 >   *\r
 510 >   * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded\r
 511 > @@ -590,21 +669,29 @@ void\r
 512 >  notmuch_query_set_omit_excluded (notmuch_query_t *query,\r
 513 >                                notmuch_exclude_t omit_excluded);\r
 514 >  \r
 515 > -/* Specify the sorting desired for this query. */\r
 516 > +/**\r
 517 > + * Specify the sorting desired for this query.\r
 518 > + */\r
 519 >  void\r
 520 >  notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);\r
 521 >  \r
 522 > -/* Return the sort specified for this query. See notmuch_query_set_sort. */\r
 523 > +/**\r
 524 > + * Return the sort specified for this query. See\r
 525 > + * notmuch_query_set_sort.\r
 526 > + */\r
 527 >  notmuch_sort_t\r
 528 >  notmuch_query_get_sort (notmuch_query_t *query);\r
 529 >  \r
 530 > -/* Add a tag that will be excluded from the query results by default.\r
 531 > +/**\r
 532 > + * Add a tag that will be excluded from the query results by default.\r
 533 >   * This exclusion will be overridden if this tag appears explicitly in\r
 534 > - * the query. */\r
 535 > + * the query.\r
 536 > + */\r
 537 >  void\r
 538 >  notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);\r
 539 >  \r
 540 > -/* Execute a query for threads, returning a notmuch_threads_t object\r
 541 > +/**\r
 542 > + * Execute a query for threads, returning a notmuch_threads_t object\r
 543 >   * which can be used to iterate over the results. The returned threads\r
 544 >   * object is owned by the query and as such, will only be valid until\r
 545 >   * notmuch_query_destroy.\r
 546 > @@ -645,7 +732,8 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);\r
 547 >  notmuch_threads_t *\r
 548 >  notmuch_query_search_threads (notmuch_query_t *query);\r
 549 >  \r
 550 > -/* Execute a query for messages, returning a notmuch_messages_t object\r
 551 > +/**\r
 552 > + * Execute a query for messages, returning a notmuch_messages_t object\r
 553 >   * which can be used to iterate over the results. The returned\r
 554 >   * messages object is owned by the query and as such, will only be\r
 555 >   * valid until notmuch_query_destroy.\r
 556 > @@ -686,7 +774,8 @@ notmuch_query_search_threads (notmuch_query_t *query);\r
 557 >  notmuch_messages_t *\r
 558 >  notmuch_query_search_messages (notmuch_query_t *query);\r
 559 >  \r
 560 > -/* Destroy a notmuch_query_t along with any associated resources.\r
 561 > +/**\r
 562 > + * Destroy a notmuch_query_t along with any associated resources.\r
 563 >   *\r
 564 >   * This will in turn destroy any notmuch_threads_t and\r
 565 >   * notmuch_messages_t objects generated by this query, (and in\r
 566 > @@ -697,7 +786,8 @@ notmuch_query_search_messages (notmuch_query_t *query);\r
 567 >  void\r
 568 >  notmuch_query_destroy (notmuch_query_t *query);\r
 569 >  \r
 570 > -/* Is the given 'threads' iterator pointing at a valid thread.\r
 571 > +/**\r
 572 > + * Is the given 'threads' iterator pointing at a valid thread.\r
 573 >   *\r
 574 >   * When this function returns TRUE, notmuch_threads_get will return a\r
 575 >   * valid object. Whereas when this function returns FALSE,\r
 576 > @@ -709,7 +799,8 @@ notmuch_query_destroy (notmuch_query_t *query);\r
 577 >  notmuch_bool_t\r
 578 >  notmuch_threads_valid (notmuch_threads_t *threads);\r
 579 >  \r
 580 > -/* Get the current thread from 'threads' as a notmuch_thread_t.\r
 581 > +/**\r
 582 > + * Get the current thread from 'threads' as a notmuch_thread_t.\r
 583 >   *\r
 584 >   * Note: The returned thread belongs to 'threads' and has a lifetime\r
 585 >   * identical to it (and the query to which it belongs).\r
 586 > @@ -723,7 +814,8 @@ notmuch_threads_valid (notmuch_threads_t *threads);\r
 587 >  notmuch_thread_t *\r
 588 >  notmuch_threads_get (notmuch_threads_t *threads);\r
 589 >  \r
 590 > -/* Move the 'threads' iterator to the next thread.\r
 591 > +/**\r
 592 > + * Move the 'threads' iterator to the next thread.\r
 593 >   *\r
 594 >   * If 'threads' is already pointing at the last thread then the\r
 595 >   * iterator will be moved to a point just beyond that last thread,\r
 596 > @@ -736,7 +828,8 @@ notmuch_threads_get (notmuch_threads_t *threads);\r
 597 >  void\r
 598 >  notmuch_threads_move_to_next (notmuch_threads_t *threads);\r
 599 >  \r
 600 > -/* Destroy a notmuch_threads_t object.\r
 601 > +/**\r
 602 > + * Destroy a notmuch_threads_t object.\r
 603 >   *\r
 604 >   * It's not strictly necessary to call this function. All memory from\r
 605 >   * the notmuch_threads_t object will be reclaimed when the\r
 606 > @@ -745,7 +838,8 @@ notmuch_threads_move_to_next (notmuch_threads_t *threads);\r
 607 >  void\r
 608 >  notmuch_threads_destroy (notmuch_threads_t *threads);\r
 609 >  \r
 610 > -/* Return an estimate of the number of messages matching a search\r
 611 > +/**\r
 612 > + * Return an estimate of the number of messages matching a search.\r
 613 >   *\r
 614 >   * This function performs a search and returns Xapian's best\r
 615 >   * guess as to number of matching messages.\r
 616 > @@ -755,8 +849,9 @@ notmuch_threads_destroy (notmuch_threads_t *threads);\r
 617 >   */\r
 618 >  unsigned\r
 619 >  notmuch_query_count_messages (notmuch_query_t *query);\r
 620 > - \r
 621 > -/* Return the number of threads matching a search.\r
 622 > +\r
 623 > +/**\r
 624 > + * Return the number of threads matching a search.\r
 625 >   *\r
 626 >   * This function performs a search and returns the number of unique thread IDs\r
 627 >   * in the matching messages. This is the same as number of threads matching a\r
 628 > @@ -770,7 +865,8 @@ notmuch_query_count_messages (notmuch_query_t *query);\r
 629 >  unsigned\r
 630 >  notmuch_query_count_threads (notmuch_query_t *query);\r
 631 >  \r
 632 > -/* Get the thread ID of 'thread'.\r
 633 > +/**\r
 634 > + * Get the thread ID of 'thread'.\r
 635 >   *\r
 636 >   * The returned string belongs to 'thread' and as such, should not be\r
 637 >   * modified by the caller and will only be valid for as long as the\r
 638 > @@ -780,7 +876,8 @@ notmuch_query_count_threads (notmuch_query_t *query);\r
 639 >  const char *\r
 640 >  notmuch_thread_get_thread_id (notmuch_thread_t *thread);\r
 641 >  \r
 642 > -/* Get the total number of messages in 'thread'.\r
 643 > +/**\r
 644 > + * Get the total number of messages in 'thread'.\r
 645 >   *\r
 646 >   * This count consists of all messages in the database belonging to\r
 647 >   * this thread. Contrast with notmuch_thread_get_matched_messages() .\r
 648 > @@ -788,7 +885,8 @@ notmuch_thread_get_thread_id (notmuch_thread_t *thread);\r
 649 >  int\r
 650 >  notmuch_thread_get_total_messages (notmuch_thread_t *thread);\r
 651 >  \r
 652 > -/* Get a notmuch_messages_t iterator for the top-level messages in\r
 653 > +/**\r
 654 > + * Get a notmuch_messages_t iterator for the top-level messages in\r
 655 >   * 'thread' in oldest-first order.\r
 656 >   *\r
 657 >   * This iterator will not necessarily iterate over all of the messages\r
 658 > @@ -800,7 +898,8 @@ notmuch_thread_get_total_messages (notmuch_thread_t *thread);\r
 659 >  notmuch_messages_t *\r
 660 >  notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);\r
 661 >  \r
 662 > -/* Get a notmuch_thread_t iterator for all messages in 'thread' in\r
 663 > +/**\r
 664 > + * Get a notmuch_thread_t iterator for all messages in 'thread' in\r
 665 >   * oldest-first order.\r
 666 >   *\r
 667 >   * The returned list will be destroyed when the thread is destroyed.\r
 668 > @@ -808,7 +907,8 @@ notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);\r
 669 >  notmuch_messages_t *\r
 670 >  notmuch_thread_get_messages (notmuch_thread_t *thread);\r
 671 >  \r
 672 > -/* Get the number of messages in 'thread' that matched the search.\r
 673 > +/**\r
 674 > + * Get the number of messages in 'thread' that matched the search.\r
 675 >   *\r
 676 >   * This count includes only the messages in this thread that were\r
 677 >   * matched by the search from which the thread was created and were\r
 678 > @@ -819,7 +919,8 @@ notmuch_thread_get_messages (notmuch_thread_t *thread);\r
 679 >  int\r
 680 >  notmuch_thread_get_matched_messages (notmuch_thread_t *thread);\r
 681 >  \r
 682 > -/* Get the authors of 'thread' as a UTF-8 string.\r
 683 > +/**\r
 684 > + * Get the authors of 'thread' as a UTF-8 string.\r
 685 >   *\r
 686 >   * The returned string is a comma-separated list of the names of the\r
 687 >   * authors of mail messages in the query results that belong to this\r
 688 > @@ -833,7 +934,8 @@ notmuch_thread_get_matched_messages (notmuch_thread_t *thread);\r
 689 >  const char *\r
 690 >  notmuch_thread_get_authors (notmuch_thread_t *thread);\r
 691 >  \r
 692 > -/* Get the subject of 'thread' as a UTF-8 string.\r
 693 > +/**\r
 694 > + * Get the subject of 'thread' as a UTF-8 string.\r
 695 >   *\r
 696 >   * The subject is taken from the first message (according to the query\r
 697 >   * order---see notmuch_query_set_sort) in the query results that\r
 698 > @@ -847,17 +949,20 @@ notmuch_thread_get_authors (notmuch_thread_t *thread);\r
 699 >  const char *\r
 700 >  notmuch_thread_get_subject (notmuch_thread_t *thread);\r
 701 >  \r
 702 > -/* Get the date of the oldest message in 'thread' as a time_t value.\r
 703 > +/**\r
 704 > + * Get the date of the oldest message in 'thread' as a time_t value.\r
 705 >   */\r
 706 >  time_t\r
 707 >  notmuch_thread_get_oldest_date (notmuch_thread_t *thread);\r
 708 >  \r
 709 > -/* Get the date of the newest message in 'thread' as a time_t value.\r
 710 > +/**\r
 711 > + * Get the date of the newest message in 'thread' as a time_t value.\r
 712 >   */\r
 713 >  time_t\r
 714 >  notmuch_thread_get_newest_date (notmuch_thread_t *thread);\r
 715 >  \r
 716 > -/* Get the tags for 'thread', returning a notmuch_tags_t object which\r
 717 > +/**\r
 718 > + * Get the tags for 'thread', returning a notmuch_tags_t object which\r
 719 >   * can be used to iterate over all tags.\r
 720 >   *\r
 721 >   * Note: In the Notmuch database, tags are stored on individual\r
 722 > @@ -896,11 +1001,14 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread);\r
 723 >  notmuch_tags_t *\r
 724 >  notmuch_thread_get_tags (notmuch_thread_t *thread);\r
 725 >  \r
 726 > -/* Destroy a notmuch_thread_t object. */\r
 727 > +/**\r
 728 > + * Destroy a notmuch_thread_t object.\r
 729 > + */\r
 730 >  void\r
 731 >  notmuch_thread_destroy (notmuch_thread_t *thread);\r
 732 >  \r
 733 > -/* Is the given 'messages' iterator pointing at a valid message.\r
 734 > +/**\r
 735 > + * Is the given 'messages' iterator pointing at a valid message.\r
 736 >   *\r
 737 >   * When this function returns TRUE, notmuch_messages_get will return a\r
 738 >   * valid object. Whereas when this function returns FALSE,\r
 739 > @@ -912,7 +1020,8 @@ notmuch_thread_destroy (notmuch_thread_t *thread);\r
 740 >  notmuch_bool_t\r
 741 >  notmuch_messages_valid (notmuch_messages_t *messages);\r
 742 >  \r
 743 > -/* Get the current message from 'messages' as a notmuch_message_t.\r
 744 > +/**\r
 745 > + * Get the current message from 'messages' as a notmuch_message_t.\r
 746 >   *\r
 747 >   * Note: The returned message belongs to 'messages' and has a lifetime\r
 748 >   * identical to it (and the query to which it belongs).\r
 749 > @@ -926,7 +1035,8 @@ notmuch_messages_valid (notmuch_messages_t *messages);\r
 750 >  notmuch_message_t *\r
 751 >  notmuch_messages_get (notmuch_messages_t *messages);\r
 752 >  \r
 753 > -/* Move the 'messages' iterator to the next message.\r
 754 > +/**\r
 755 > + * Move the 'messages' iterator to the next message.\r
 756 >   *\r
 757 >   * If 'messages' is already pointing at the last message then the\r
 758 >   * iterator will be moved to a point just beyond that last message,\r
 759 > @@ -939,7 +1049,8 @@ notmuch_messages_get (notmuch_messages_t *messages);\r
 760 >  void\r
 761 >  notmuch_messages_move_to_next (notmuch_messages_t *messages);\r
 762 >  \r
 763 > -/* Destroy a notmuch_messages_t object.\r
 764 > +/**\r
 765 > + * Destroy a notmuch_messages_t object.\r
 766 >   *\r
 767 >   * It's not strictly necessary to call this function. All memory from\r
 768 >   * the notmuch_messages_t object will be reclaimed when the containing\r
 769 > @@ -948,7 +1059,8 @@ notmuch_messages_move_to_next (notmuch_messages_t *messages);\r
 770 >  void\r
 771 >  notmuch_messages_destroy (notmuch_messages_t *messages);\r
 772 >  \r
 773 > -/* Return a list of tags from all messages.\r
 774 > +/**\r
 775 > + * Return a list of tags from all messages.\r
 776 >   *\r
 777 >   * The resulting list is guaranteed not to contain duplicated tags.\r
 778 >   *\r
 779 > @@ -963,7 +1075,8 @@ notmuch_messages_destroy (notmuch_messages_t *messages);\r
 780 >  notmuch_tags_t *\r
 781 >  notmuch_messages_collect_tags (notmuch_messages_t *messages);\r
 782 >  \r
 783 > -/* Get the message ID of 'message'.\r
 784 > +/**\r
 785 > + * Get the message ID of 'message'.\r
 786 >   *\r
 787 >   * The returned string belongs to 'message' and as such, should not be\r
 788 >   * modified by the caller and will only be valid for as long as the\r
 789 > @@ -977,7 +1090,8 @@ notmuch_messages_collect_tags (notmuch_messages_t *messages);\r
 790 >  const char *\r
 791 >  notmuch_message_get_message_id (notmuch_message_t *message);\r
 792 >  \r
 793 > -/* Get the thread ID of 'message'.\r
 794 > +/**\r
 795 > + * Get the thread ID of 'message'.\r
 796 >   *\r
 797 >   * The returned string belongs to 'message' and as such, should not be\r
 798 >   * modified by the caller and will only be valid for as long as the\r
 799 > @@ -991,7 +1105,8 @@ notmuch_message_get_message_id (notmuch_message_t *message);\r
 800 >  const char *\r
 801 >  notmuch_message_get_thread_id (notmuch_message_t *message);\r
 802 >  \r
 803 > -/* Get a notmuch_messages_t iterator for all of the replies to\r
 804 > +/**\r
 805 > + * Get a notmuch_messages_t iterator for all of the replies to\r
 806 >   * 'message'.\r
 807 >   *\r
 808 >   * Note: This call only makes sense if 'message' was ultimately\r
 809 > @@ -1011,7 +1126,8 @@ notmuch_message_get_thread_id (notmuch_message_t *message);\r
 810 >  notmuch_messages_t *\r
 811 >  notmuch_message_get_replies (notmuch_message_t *message);\r
 812 >  \r
 813 > -/* Get a filename for the email corresponding to 'message'.\r
 814 > +/**\r
 815 > + * Get a filename for the email corresponding to 'message'.\r
 816 >   *\r
 817 >   * The returned filename is an absolute filename, (the initial\r
 818 >   * component will match notmuch_database_get_path() ).\r
 819 > @@ -1029,7 +1145,8 @@ notmuch_message_get_replies (notmuch_message_t *message);\r
 820 >  const char *\r
 821 >  notmuch_message_get_filename (notmuch_message_t *message);\r
 822 >  \r
 823 > -/* Get all filenames for the email corresponding to 'message'.\r
 824 > +/**\r
 825 > + * Get all filenames for the email corresponding to 'message'.\r
 826 >   *\r
 827 >   * Returns a notmuch_filenames_t iterator listing all the filenames\r
 828 >   * associated with 'message'. These files may not have identical\r
 829 > @@ -1041,31 +1158,40 @@ notmuch_message_get_filename (notmuch_message_t *message);\r
 830 >  notmuch_filenames_t *\r
 831 >  notmuch_message_get_filenames (notmuch_message_t *message);\r
 832 >  \r
 833 > -/* Message flags */\r
 834 > +/**\r
 835 > + * Message flags.\r
 836 > + */\r
 837 >  typedef enum _notmuch_message_flag {\r
 838 >      NOTMUCH_MESSAGE_FLAG_MATCH,\r
 839 >      NOTMUCH_MESSAGE_FLAG_EXCLUDED\r
 840 >  } notmuch_message_flag_t;\r
 841 >  \r
 842 > -/* Get a value of a flag for the email corresponding to 'message'. */\r
 843 > +/**\r
 844 > + * Get a value of a flag for the email corresponding to 'message'.\r
 845 > + */\r
 846 >  notmuch_bool_t\r
 847 >  notmuch_message_get_flag (notmuch_message_t *message,\r
 848 >                         notmuch_message_flag_t flag);\r
 849 >  \r
 850 > -/* Set a value of a flag for the email corresponding to 'message'. */\r
 851 > +/**\r
 852 > + * Set a value of a flag for the email corresponding to 'message'.\r
 853 > + */\r
 854 >  void\r
 855 >  notmuch_message_set_flag (notmuch_message_t *message,\r
 856 >                         notmuch_message_flag_t flag, notmuch_bool_t value);\r
 857 >  \r
 858 > -/* Get the date of 'message' as a time_t value.\r
 859 > +/**\r
 860 > + * Get the date of 'message' as a time_t value.\r
 861 >   *\r
 862 >   * For the original textual representation of the Date header from the\r
 863 >   * message call notmuch_message_get_header() with a header value of\r
 864 > - * "date". */\r
 865 > + * "date".\r
 866 > + */\r
 867 >  time_t\r
 868 >  notmuch_message_get_date  (notmuch_message_t *message);\r
 869 >  \r
 870 > -/* Get the value of the specified header from 'message' as a UTF-8 string.\r
 871 > +/**\r
 872 > + * Get the value of the specified header from 'message' as a UTF-8 string.\r
 873 >   *\r
 874 >   * Common headers are stored in the database when the message is\r
 875 >   * indexed and will be returned from the database.  Other headers will\r
 876 > @@ -1083,7 +1209,8 @@ notmuch_message_get_date  (notmuch_message_t *message);\r
 877 >  const char *\r
 878 >  notmuch_message_get_header (notmuch_message_t *message, const char *header);\r
 879 >  \r
 880 > -/* Get the tags for 'message', returning a notmuch_tags_t object which\r
 881 > +/**\r
 882 > + * Get the tags for 'message', returning a notmuch_tags_t object which\r
 883 >   * can be used to iterate over all tags.\r
 884 >   *\r
 885 >   * The tags object is owned by the message and as such, will only be\r
 886 > @@ -1116,10 +1243,13 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header);\r
 887 >  notmuch_tags_t *\r
 888 >  notmuch_message_get_tags (notmuch_message_t *message);\r
 889 >  \r
 890 > -/* The longest possible tag value. */\r
 891 > +/**\r
 892 > + * The longest possible tag value.\r
 893 > + */\r
 894 >  #define NOTMUCH_TAG_MAX 200\r
 895 >  \r
 896 > -/* Add a tag to the given message.\r
 897 > +/**\r
 898 > + * Add a tag to the given message.\r
 899 >   *\r
 900 >   * Return value:\r
 901 >   *\r
 902 > @@ -1136,7 +1266,8 @@ notmuch_message_get_tags (notmuch_message_t *message);\r
 903 >  notmuch_status_t\r
 904 >  notmuch_message_add_tag (notmuch_message_t *message, const char *tag);\r
 905 >  \r
 906 > -/* Remove a tag from the given message.\r
 907 > +/**\r
 908 > + * Remove a tag from the given message.\r
 909 >   *\r
 910 >   * Return value:\r
 911 >   *\r
 912 > @@ -1153,7 +1284,8 @@ notmuch_message_add_tag (notmuch_message_t *message, const char *tag);\r
 913 >  notmuch_status_t\r
 914 >  notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);\r
 915 >  \r
 916 > -/* Remove all tags from the given message.\r
 917 > +/**\r
 918 > + * Remove all tags from the given message.\r
 919 >   *\r
 920 >   * See notmuch_message_freeze for an example showing how to safely\r
 921 >   * replace tag values.\r
 922 > @@ -1164,7 +1296,8 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);\r
 923 >  notmuch_status_t\r
 924 >  notmuch_message_remove_all_tags (notmuch_message_t *message);\r
 925 >  \r
 926 > -/* Add/remove tags according to maildir flags in the message filename(s)\r
 927 > +/**\r
 928 > + * Add/remove tags according to maildir flags in the message filename(s).\r
 929 >   *\r
 930 >   * This function examines the filenames of 'message' for maildir\r
 931 >   * flags, and adds or removes tags on 'message' as follows when these\r
 932 > @@ -1198,7 +1331,8 @@ notmuch_message_remove_all_tags (notmuch_message_t *message);\r
 933 >  notmuch_status_t\r
 934 >  notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);\r
 935 >  \r
 936 > -/* Rename message filename(s) to encode tags as maildir flags\r
 937 > +/**\r
 938 > + * Rename message filename(s) to encode tags as maildir flags.\r
 939 >   *\r
 940 >   * Specifically, for each filename corresponding to this message:\r
 941 >   *\r
 942 > @@ -1234,7 +1368,8 @@ notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);\r
 943 >  notmuch_status_t\r
 944 >  notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);\r
 945 >  \r
 946 > -/* Freeze the current state of 'message' within the database.\r
 947 > +/**\r
 948 > + * Freeze the current state of 'message' within the database.\r
 949 >   *\r
 950 >   * This means that changes to the message state, (via\r
 951 >   * notmuch_message_add_tag, notmuch_message_remove_tag, and\r
 952 > @@ -1277,7 +1412,8 @@ notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);\r
 953 >  notmuch_status_t\r
 954 >  notmuch_message_freeze (notmuch_message_t *message);\r
 955 >  \r
 956 > -/* Thaw the current 'message', synchronizing any changes that may have\r
 957 > +/**\r
 958 > + * Thaw the current 'message', synchronizing any changes that may have\r
 959 >   * occurred while 'message' was frozen into the notmuch database.\r
 960 >   *\r
 961 >   * See notmuch_message_freeze for an example of how to use this\r
 962 > @@ -1300,7 +1436,8 @@ notmuch_message_freeze (notmuch_message_t *message);\r
 963 >  notmuch_status_t\r
 964 >  notmuch_message_thaw (notmuch_message_t *message);\r
 965 >  \r
 966 > -/* Destroy a notmuch_message_t object.\r
 967 > +/**\r
 968 > + * Destroy a notmuch_message_t object.\r
 969 >   *\r
 970 >   * It can be useful to call this function in the case of a single\r
 971 >   * query object with many messages in the result, (such as iterating\r
 972 > @@ -1311,7 +1448,8 @@ notmuch_message_thaw (notmuch_message_t *message);\r
 973 >  void\r
 974 >  notmuch_message_destroy (notmuch_message_t *message);\r
 975 >  \r
 976 > -/* Is the given 'tags' iterator pointing at a valid tag.\r
 977 > +/**\r
 978 > + * Is the given 'tags' iterator pointing at a valid tag.\r
 979 >   *\r
 980 >   * When this function returns TRUE, notmuch_tags_get will return a\r
 981 >   * valid string. Whereas when this function returns FALSE,\r
 982 > @@ -1323,7 +1461,8 @@ notmuch_message_destroy (notmuch_message_t *message);\r
 983 >  notmuch_bool_t\r
 984 >  notmuch_tags_valid (notmuch_tags_t *tags);\r
 985 >  \r
 986 > -/* Get the current tag from 'tags' as a string.\r
 987 > +/**\r
 988 > + * Get the current tag from 'tags' as a string.\r
 989 >   *\r
 990 >   * Note: The returned string belongs to 'tags' and has a lifetime\r
 991 >   * identical to it (and the query to which it ultimately belongs).\r
 992 > @@ -1334,7 +1473,8 @@ notmuch_tags_valid (notmuch_tags_t *tags);\r
 993 >  const char *\r
 994 >  notmuch_tags_get (notmuch_tags_t *tags);\r
 995 >  \r
 996 > -/* Move the 'tags' iterator to the next tag.\r
 997 > +/**\r
 998 > + * Move the 'tags' iterator to the next tag.\r
 999 >   *\r
1000 >   * If 'tags' is already pointing at the last tag then the iterator\r
1001 >   * will be moved to a point just beyond that last tag, (where\r
1002 > @@ -1347,7 +1487,8 @@ notmuch_tags_get (notmuch_tags_t *tags);\r
1003 >  void\r
1004 >  notmuch_tags_move_to_next (notmuch_tags_t *tags);\r
1005 >  \r
1006 > -/* Destroy a notmuch_tags_t object.\r
1007 > +/**\r
1008 > + * Destroy a notmuch_tags_t object.\r
1009 >   *\r
1010 >   * It's not strictly necessary to call this function. All memory from\r
1011 >   * the notmuch_tags_t object will be reclaimed when the containing\r
1012 > @@ -1356,7 +1497,8 @@ notmuch_tags_move_to_next (notmuch_tags_t *tags);\r
1013 >  void\r
1014 >  notmuch_tags_destroy (notmuch_tags_t *tags);\r
1015 >  \r
1016 > -/* Store an mtime within the database for 'directory'.\r
1017 > +/**\r
1018 > + * Store an mtime within the database for 'directory'.\r
1019 >   *\r
1020 >   * The 'directory' should be an object retrieved from the database\r
1021 >   * with notmuch_database_get_directory for a particular path.\r
1022 > @@ -1396,35 +1538,44 @@ notmuch_status_t\r
1023 >  notmuch_directory_set_mtime (notmuch_directory_t *directory,\r
1024 >                            time_t mtime);\r
1025 >  \r
1026 > -/* Get the mtime of a directory, (as previously stored with\r
1027 > +/**\r
1028 > + * Get the mtime of a directory, (as previously stored with\r
1029 >   * notmuch_directory_set_mtime).\r
1030 >   *\r
1031 >   * Returns 0 if no mtime has previously been stored for this\r
1032 > - * directory.*/\r
1033 > + * directory.\r
1034 > + */\r
1035 >  time_t\r
1036 >  notmuch_directory_get_mtime (notmuch_directory_t *directory);\r
1037 >  \r
1038 > -/* Get a notmuch_filenames_t iterator listing all the filenames of\r
1039 > +/**\r
1040 > + * Get a notmuch_filenames_t iterator listing all the filenames of\r
1041 >   * messages in the database within the given directory.\r
1042 >   *\r
1043 >   * The returned filenames will be the basename-entries only (not\r
1044 > - * complete paths). */\r
1045 > + * complete paths).\r
1046 > + */\r
1047 >  notmuch_filenames_t *\r
1048 >  notmuch_directory_get_child_files (notmuch_directory_t *directory);\r
1049 >  \r
1050 > -/* Get a notmuch_filenams_t iterator listing all the filenames of\r
1051 > +/**\r
1052 > + * Get a notmuch_filenams_t iterator listing all the filenames of\r
1053 >   * sub-directories in the database within the given directory.\r
1054 >   *\r
1055 >   * The returned filenames will be the basename-entries only (not\r
1056 > - * complete paths). */\r
1057 > + * complete paths).\r
1058 > + */\r
1059 >  notmuch_filenames_t *\r
1060 >  notmuch_directory_get_child_directories (notmuch_directory_t *directory);\r
1061 >  \r
1062 > -/* Destroy a notmuch_directory_t object. */\r
1063 > +/**\r
1064 > + * Destroy a notmuch_directory_t object.\r
1065 > + */\r
1066 >  void\r
1067 >  notmuch_directory_destroy (notmuch_directory_t *directory);\r
1068 >  \r
1069 > -/* Is the given 'filenames' iterator pointing at a valid filename.\r
1070 > +/**\r
1071 > + * Is the given 'filenames' iterator pointing at a valid filename.\r
1072 >   *\r
1073 >   * When this function returns TRUE, notmuch_filenames_get will return\r
1074 >   * a valid string. Whereas when this function returns FALSE,\r
1075 > @@ -1436,7 +1587,8 @@ notmuch_directory_destroy (notmuch_directory_t *directory);\r
1076 >  notmuch_bool_t\r
1077 >  notmuch_filenames_valid (notmuch_filenames_t *filenames);\r
1078 >  \r
1079 > -/* Get the current filename from 'filenames' as a string.\r
1080 > +/**\r
1081 > + * Get the current filename from 'filenames' as a string.\r
1082 >   *\r
1083 >   * Note: The returned string belongs to 'filenames' and has a lifetime\r
1084 >   * identical to it (and the directory to which it ultimately belongs).\r
1085 > @@ -1447,7 +1599,8 @@ notmuch_filenames_valid (notmuch_filenames_t *filenames);\r
1086 >  const char *\r
1087 >  notmuch_filenames_get (notmuch_filenames_t *filenames);\r
1088 >  \r
1089 > -/* Move the 'filenames' iterator to the next filename.\r
1090 > +/**\r
1091 > + * Move the 'filenames' iterator to the next filename.\r
1092 >   *\r
1093 >   * If 'filenames' is already pointing at the last filename then the\r
1094 >   * iterator will be moved to a point just beyond that last filename,\r
1095 > @@ -1460,7 +1613,8 @@ notmuch_filenames_get (notmuch_filenames_t *filenames);\r
1096 >  void\r
1097 >  notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);\r
1098 >  \r
1099 > -/* Destroy a notmuch_filenames_t object.\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 > @@ -1472,6 +1626,8 @@ notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);\r
1106 >  void\r
1107 >  notmuch_filenames_destroy (notmuch_filenames_t *filenames);\r
1108 >  \r
1109 > +/* @} */\r
1110 > +\r
1111 >  NOTMUCH_END_DECLS\r
1112 >  \r
1113 >  #endif\r
1114 > -- \r
1115 > 1.8.4.2\r
1116 >\r
1117 > _______________________________________________\r
1118 > notmuch mailing list\r
1119 > notmuch@notmuchmail.org\r
1120 > http://notmuchmail.org/mailman/listinfo/notmuch\r