From 7422e8c914d9b834698d5b0a6de1a2539d175b87 Mon Sep 17 00:00:00 2001
From: JUSHUANGHUI LI <oodadoudou@gmail.com>
Date: Fri, 18 Sep 2026 11:52:18 +0200
Subject: [PATCH] docs: clarify ownership of jv arguments and results (#3627)

The ownership comment in `jv.h` currently says every `jv_*` function
except `jv_copy` consumes its input. Several accessors and
object-iteration functions borrow their arguments instead, which makes
that guidance misleading for callers and language bindings.

Document the borrowing exceptions beside their declarations, including
numeric helpers and `jv_show`. Clarify that returned `jv` values are
owned, while the pointers returned by `jv_string_value` and
`jv_number_get_literal` belong to their input values. This changes
comments only.
---
 src/jv.h | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/jv.h b/src/jv.h
index b9710610..0eac43ea 100644
--- a/src/jv.h
+++ b/src/jv.h
@@ -43,17 +43,23 @@ typedef struct {
 } jv;
 
 /*
- * All jv_* functions consume (decref) input and produce (incref) output
- * Except jv_copy
+ * Unless noted otherwise, functions consume their jv arguments. Returned jv
+ * values are owned. Pass jv_copy(value) to retain a value across a consuming
+ * call, and release each owned value with jv_free() when no longer needed.
+ * Borrowed arguments are not consumed; the caller retains ownership.
+ * Returned jv values are owned even when the arguments are borrowed.
  */
 
+/* These functions borrow their jv arguments. */
 jv_kind jv_get_kind(jv);
 const char* jv_kind_name(jv_kind);
 static int jv_is_valid(jv x) { return jv_get_kind(x) != JV_KIND_INVALID; }
 
+/* Borrows its argument and returns a new reference to the same value. */
 jv jv_copy(jv);
 void jv_free(jv);
 
+/* Borrows its argument. */
 int jv_get_refcnt(jv);
 
 int jv_equal(jv, jv);
@@ -72,12 +78,15 @@ jv jv_bool(int);
 
 jv jv_number(double);
 jv jv_number_with_literal(const char*);
+/* These functions borrow their jv arguments. */
 double jv_number_value(jv);
 int jv_is_integer(jv);
 jv jv_number_abs(jv);
 jv jv_number_negate(jv);
 
+/* Borrows its argument. */
 int jv_number_has_literal(jv);
+/* Borrows its argument; the returned string belongs to the number. */
 const char* jv_number_get_literal(jv);
 
 jv jv_array(void);
@@ -127,6 +136,7 @@ jv jv_string_empty(int len);
 int jv_string_length_bytes(jv);
 int jv_string_length_codepoints(jv);
 unsigned long jv_string_hash(jv);
+/* Borrows its argument; the returned string belongs to the value. */
 const char* jv_string_value(jv);
 jv jv_string_indexes(jv j, jv k);
 jv jv_string_slice(jv j, int start, int end);
@@ -150,6 +160,7 @@ int jv_object_length(jv object);
 jv jv_object_merge(jv, jv);
 jv jv_object_merge_recursive(jv, jv);
 
+/* Object iteration borrows the object; returned keys and values are owned. */
 int jv_object_iter(jv);
 int jv_object_iter_next(jv, int);
 int jv_object_iter_valid(jv, int);
@@ -213,6 +224,7 @@ jv jv_object_iter_value(jv, int);
 
 
 
+/* Borrows its argument. */
 int jv_get_refcnt(jv);
 
 enum jv_print_flags {
@@ -232,6 +244,7 @@ enum jv_print_flags {
     ((n) < 0 || (n) > 7 ? JV_PRINT_TAB | JV_PRINT_PRETTY : (n) << 8 | JV_PRINT_PRETTY)
 void jv_dumpf(jv, FILE *f, int flags);
 void jv_dump(jv, int flags);
+/* Borrows its argument, unlike jv_dump() and jv_dumpf(). */
 void jv_show(jv, int flags);
 jv jv_dump_string(jv, int flags);
 char *jv_dump_string_trunc(jv x, char *outbuf, size_t bufsize);