[augeas-devel] augeas: master - * src/augeas.h: improve some comments

[David Lutterkort]

Gitweb:        http://git.fedorahosted.org/git/augeas.git?p=augeas.git;a=commitdiff;h=90464320301f5ce13e8d6f13bb1211d22bd014fb
Commit:        90464320301f5ce13e8d6f13bb1211d22bd014fb
Parent:        64115058d19beef65dbebdeab3271b6b24f7a412
Author:        David Lutterkort <lutter at redhat.com>
AuthorDate:    Mon Apr 13 10:24:17 2009 -0700
Committer:     David Lutterkort <lutter at redhat.com>
CommitterDate: Mon Apr 13 10:24:17 2009 -0700

* src/augeas.h: improve some comments

---
 src/augeas.h |   11 ++++++++---
 1 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/augeas.h b/src/augeas.h
index 9792bad..972ea35 100644
--- a/src/augeas.h
+++ b/src/augeas.h
@@ -111,7 +111,12 @@ int aug_defnode(augeas *aug, const char *name, const char *expr,
  * Lookup the value associated with PATH. VALUE can be NULL, in which case
  * it is ignored. If VALUE is not NULL, it is used to return a pointer to
  * the value associated with PATH if PATH matches exactly one node. If PATH
- * matches no nodes or more than one node, *VALUE is set to NULL.
+ * matches no nodes or more than one node, *VALUE is set to NULL. Note that
+ * it is perfectly legal for nodes to have a NULL value, and that that by
+ * itself does not indicate an error.
+ *
+ * The string *VALUE must not be freed by the caller, and is valid as long
+ * as its node remains unchanged.
  *
  * Returns:
  * 1 if there is exactly one node matching PATH, 0 if there is none,
@@ -123,8 +128,8 @@ int aug_get(const augeas *aug, const char *path, const char **value);
 /* Function: aug_set
  *
  * Set the value associated with PATH to VALUE. VALUE is copied into the
- * internal data structure. Intermediate entries are created if they don't
- * exist.
+ * internal data structure, and the caller is responsible for freeing
+ * it. Intermediate entries are created if they don't exist.
  *
  * Returns:
  * 0 on success, -1 on error. It is an error if more than one node