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>

diff --git a/list.c b/list.c
index 0d00f81b424bc6985360c4c3528b6f2781ee8051..321861c8eb7d741c17a1cc764e4e648635640b13 100644 (file)
--- 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 b31d00795804bd1e443725eb83a328ffcde92042..abba660826c33fd64acc3e46a2d6f5f1510dfd04 100644 (file)
--- 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);