- * Note: It is *not* an error if the specified configuration file does
- * not exist. In this case, a default configuration will be created
- * and returned. Subsequently calling notmuch_config_save will cause
- * the configuration to be written to the filename specified at the
- * time of notmuch_config_open.
+ * FILE NOT FOUND: When the specified configuration file (whether from
+ * 'filename' or the $NOTMUCH_CONFIG environment variable) does not
+ * exist, the behavior of this function depends on the 'is_new_ret'
+ * variable.
+ *
+ * If is_new_ret is NULL, then a "file not found" message will be
+ * printed to stderr and NULL will be returned.
+
+ * If is_new_ret is non-NULL then a default configuration will be
+ * returned and *is_new_ret will be set to 1 on return so that
+ * the caller can recognize this case.