simplify error-to-string interface

1 files changed, 14 insertions, 10 deletions

diff --git a/pom.h b/pom.h
index ea38a3d..9adb156 100644
--- a/pom.h
+++ b/pom.h
@@ -90,6 +90,11 @@ typedef struct pom_item {
 
 /// Load a configuration using a `read`-like function.
 ///
+/// Most of the time, you won't need this function:
+/// use \ref pom_load_file to load from a `FILE *`,
+/// \ref pom_load_path to load from a path,
+/// and \ref pom_load_string to load from a string.
+///
 /// On success, a configuration is returned and `*error` is set to `NULL`
 /// if `error` is not `NULL`.
 ///
@@ -99,11 +104,6 @@ typedef struct pom_item {
 /// there isn’t even enough memory for an out-of-memory
 /// error, `NULL` is returned and `*error` is set to `NULL`.
 ///
-/// Most of the time, you won't need this function:
-/// use \ref pom_load_file to load from a `FILE *`,
-/// \ref pom_load_path to load from a path,
-/// and \ref pom_load_string to load from a string.
-///
 /// `read_func` will be passed the `userdata` pointer passed to this function,
 /// a buffer, and the length of that buffer (which will be nonzero).
 /// It must fill out the buffer as much as possible,
@@ -121,7 +121,7 @@ pom_load(const char *filename,
 POM__MUST_USE_R;
 
 #ifndef POM_NO_STDIO
-/// Load configuration from a `FILE *`, which should be opened in binary mode.
+/// Load configuration from a `FILE *` opened in read-binary mode.
 ///
 /// On success, a configuration is returned and `*error` is set to `NULL`
 /// if `error` is not `NULL`.
@@ -187,7 +187,11 @@ pom_error_file(const pom_error *error);
 uint64_t
 pom_error_line(const pom_error *error);
 
-/// Get next error in error list.
+/// Get next error in error list, or `NULL` if this is the last error.
+///
+/// You can only call \ref pom_error_message, \ref pom_error_file, and \ref pom_error_line
+/// on the returned error, not \ref pom_error_print or \ref pom_error_to_string.
+/// (This is enforced with `const`-ness.)
 const pom_error *
 pom_error_next(const pom_error *error);
 
@@ -196,14 +200,14 @@ pom_error_next(const pom_error *error);
 ///
 /// Includes every error in an error list (see \ref pom_error_next).
 void
-pom_error_print(const pom_error *error);
+pom_error_print(pom_error *error);
 #endif
 
-/// Convert error to string. Return value must be `free()`d.
+/// Convert error to string. Return value is valid until `error` is `free()`’d.
 ///
 /// Includes every error in an error list (see \ref pom_error_next).
 POM__MUST_USE_L
-char *
+const char *
 pom_error_to_string(pom_error *error)
 POM__MUST_USE_R;