Add a few notes on the return value of uci_lookup_ptr().

While at it, use UCI_OK instead of literal integer 0 for return value of
uci_lookup_ptr().

Signed-off-by: Yousong Zhou <yszhou4tech@gmail.com>

2 files changed, 10 insertions, 2 deletions

diff --git a/list.c b/list.c
index 0d00f81..321861c 100644
--- a/list.c
+++ b/list.c
@@ -431,11 +431,12 @@ uci_lookup_ptr(struct uci_context *ctx, struct uci_ptr *ptr, char *str, bool ext
 complete:
 	ptr->flags |= UCI_LOOKUP_COMPLETE;
 abort:
-	return 0;
+	return UCI_OK;
 
 notfound:
 	UCI_THROW(ctx, UCI_ERR_NOTFOUND);
-	return 0;
+	/* not a chance here */
+	return UCI_ERR_NOTFOUND;
 }
 
 __private struct uci_element *
diff --git a/uci.h b/uci.h
index b31d007..abba660 100644
--- a/uci.h
+++ b/uci.h
@@ -154,6 +154,13 @@ extern int uci_unload(struct uci_context *ctx, struct uci_package *p);
  * Note: uci_lookup_ptr will automatically load a config package if necessary
  * @str must not be constant, as it will be modified and used for the strings inside @ptr,
  * thus it must also be available as long as @ptr is in use.
+ *
+ * This function returns UCI_ERR_NOTFOUND if the package specified in the tuple
+ * string cannot be found.  Otherwise it will return UCI_OK.
+ *
+ * Note that failures in looking up other parts, if they are also specfied,
+ * including section and option, will also have a return value UCI_OK but with
+ * ptr->flags * UCI_LOOKUP_COMPLETE not set.
  */
 extern int uci_lookup_ptr(struct uci_context *ctx, struct uci_ptr *ptr, char *str, bool extended);