Implement pom_conf_next_item

1 files changed, 8 insertions, 5 deletions

diff --git a/pom.h b/pom.h
index f37c974..50897b8 100644
--- a/pom.h
+++ b/pom.h
@@ -20,7 +20,7 @@
 /// distinct configurations in different threads without worry.
 
 /// \mainpage libpom doxygen documentation
-/// 
+///
 /// See \ref pom.h for all types/functions.
 #ifndef POM_H_
 #define POM_H_
@@ -75,7 +75,7 @@ typedef struct pom_item {
 	/// The value of the key.
 	///
 	/// This pointer is valid until \ref pom_conf_free is called.
-	const char *val;
+	const char *value;
 	/// The file where the key was defined.
 	///
 	/// This pointer is valid until \ref pom_conf_free is called.
@@ -331,7 +331,7 @@ char **
 pom_conf_get_list(const pom_conf *conf, const char *key)
 POM__MUST_USE_R;
 
-/// Extract section out of POM configuration.
+/// Extract section out of POM configuration. Invalidated if \ref pom_conf_merge is called.
 ///
 /// Specifically, this returns the configuration consisting of all keys
 /// prefixed by `section.`, with that prefix removed, and their corresponding
@@ -372,7 +372,7 @@ pom_conf_next_key(const pom_conf *conf, pom_key_iter **iter);
 /// Get all key-value pairs in `conf`.
 ///
 /// The first call to this function should be with `*iter = NULL`.
-/// Each time it is called with the same `iter`, it returns the next
+/// Each time it is called with the same `conf` and `iter`, it returns the next
 /// key-value pair in `conf`.
 /// After all items have been returned (or if an out-of-memory error occurs),
 /// `NULL` is returned, any memory
@@ -384,6 +384,8 @@ pom_conf_next_key(const pom_conf *conf, pom_key_iter **iter);
 /// you should still call this function repeatedly until you get `NULL`;
 /// otherwise memory associated with the iterator may be leaked.
 ///
+/// The returned pointer is only valid until the next call to \ref pom_conf_next_item.
+///
 /// The correct usage for this function is:
 ///
 /// ```C
@@ -409,7 +411,8 @@ pom_conf *
 pom_conf_copy(const pom_conf *conf)
 POM__MUST_USE_R;
 
-/// Merge keys from `other` into `conf`, preferring keys in `other`.
+/// Merge keys from `other` into `conf`, preferring keys in `other`. This invalidates
+/// all sections made with \ref pom_conf_section.
 void
 pom_conf_merge(pom_conf *conf, const pom_conf *other);