- * The intention is for the caller to use the mtime to allow efficient
- * identification of new messages to be added to the database. The
- * recommended usage is as follows:
- *
- * o Read the mtime of a directory from the filesystem
- *
- * o Call add_message for all mail files in the directory
- *
- * o Call notmuch_database_set_directory_mtime
- *
- * Then, when wanting to check for updates to the directory in the
- * future, the client can call notmuch_database_get_directory_mtime
- * and know that it only needs to add files if the mtime of the
- * directory and files are newer than the stored timestamp.
- *
- * Note: The notmuch_database_get_directory_mtime function does not
- * allow the caller to distinguish a timestamp of 0 from a
- * non-existent timestamp. So don't store a timestamp of 0 unless you
- * are comfortable with that.
- *
- * Return value:
- *
- * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database.
- *
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
- * occurred, mtime not stored.
+ * The stored mtime of the directory along with a list of messages
+ * and directories in the database contained in 'dirname' are
+ * returned in 'directory'. The entries are sorted by filename.