Merge pull request #14396 from roberth/c-api-docs

doc: Improve libexpr-c docs

doc/manual/source/development/documentation.md

@@ -240,3 +240,9 @@ $ configurePhase
 $ ninja src/external-api-docs/html
 $ xdg-open src/external-api-docs/html/index.html
 ```
+
+If you use direnv, or otherwise want to run `configurePhase` in a transient shell, use:
+
+```bash
+nix-shell -A devShells.x86_64-linux.native-clangStdenv --command 'appendToVar mesonFlags "-Ddoc-gen=true"; mesonConfigurePhase'
+```

src/external-api-docs/README.md

@@ -15,7 +15,7 @@ programmatically:
 1. Embedding the evaluator
 2. Writing language plug-ins
 
-Embedding means you link the Nix C libraries in your program and use them from
+Embedding means you link the Nix C API libraries in your program and use them from
 there. Adding a plug-in means you make a library that gets loaded by the Nix
 language evaluator, specified through a configuration option.
 

src/libexpr-c/nix_api_expr.h

@@ -4,11 +4,14 @@
  * @brief Bindings to the Nix language evaluator
  *
  * See *[Embedding the Nix Evaluator](@ref nix_evaluator_example)* for an example.
- * @{
  */
 /** @file
  * @brief Main entry for the libexpr C bindings
  */
+/** @defgroup libexpr_init Initialization
+ * @ingroup libexpr
+ * @{
+ */
 
 #include "nix_api_store.h"
 #include "nix_api_util.h"
@@ -45,7 +48,10 @@ typedef struct nix_eval_state_builder nix_eval_state_builder;
  */
 typedef struct EvalState EvalState; // nix::EvalState
 
+/** @} */
+
 /** @brief A Nix language value, or thunk that may evaluate to a value.
+ * @ingroup value
  *
  * Values are the primary objects manipulated in the Nix language.
  * They are considered to be immutable from a user's perspective, but the process of evaluating a value changes its
@@ -56,7 +62,8 @@ typedef struct EvalState EvalState; // nix::EvalState
  *
  * The evaluator manages its own memory, but your use of the C API must follow the reference counting rules.
  *
- * @see value_manip
+ * @struct nix_value
+ * @see value_create, value_extract
  * @see nix_value_incref, nix_value_decref
  */
 typedef struct nix_value nix_value;
@@ -65,6 +72,7 @@ NIX_DEPRECATED("use nix_value instead") typedef nix_value Value;
 // Function prototypes
 /**
  * @brief Initialize the Nix language evaluator.
+ * @ingroup libexpr_init
  *
  * This function must be called at least once,
  * at some point before constructing a EvalState for the first time.
@@ -77,6 +85,7 @@ nix_err nix_libexpr_init(nix_c_context * context);
 
 /**
  * @brief Parses and evaluates a Nix expression from a string.
+ * @ingroup value_create
  *
  * @param[out] context Optional, stores error information
  * @param[in] state The state of the evaluation.
@@ -93,6 +102,7 @@ nix_err nix_expr_eval_from_string(
 
 /**
  * @brief Calls a Nix function with an argument.
+ * @ingroup value_create
  *
  * @param[out] context Optional, stores error information
  * @param[in] state The state of the evaluation.
@@ -107,6 +117,7 @@ nix_err nix_value_call(nix_c_context * context, EvalState * state, nix_value * f
 
 /**
  * @brief Calls a Nix function with multiple arguments.
+ * @ingroup value_create
  *
  * Technically these are functions that return functions. It is common for Nix
  * functions to be curried, so this function is useful for calling them.
@@ -126,10 +137,12 @@ nix_err nix_value_call_multi(
 
 /**
  * @brief Calls a Nix function with multiple arguments.
+ * @ingroup value_create
  *
  * Technically these are functions that return functions. It is common for Nix
  * functions to be curried, so this function is useful for calling them.
  *
+ * @def NIX_VALUE_CALL
  * @param[out] context Optional, stores error information
  * @param[in] state The state of the evaluation.
  * @param[out] value The result of the function call.
@@ -147,6 +160,7 @@ nix_err nix_value_call_multi(
 
 /**
  * @brief Forces the evaluation of a Nix value.
+ * @ingroup value_create
  *
  * The Nix interpreter is lazy, and not-yet-evaluated values can be
  * of type NIX_TYPE_THUNK instead of their actual value.
@@ -180,18 +194,20 @@ nix_err nix_value_force_deep(nix_c_context * context, EvalState * state, nix_val
 
 /**
  * @brief Create a new nix_eval_state_builder
+ * @ingroup libexpr_init
  *
  * The settings are initialized to their default value.
  * Values can be sourced elsewhere with nix_eval_state_builder_load.
  *
  * @param[out] context Optional, stores error information
  * @param[in] store The Nix store to use.
- * @return A new nix_eval_state_builder or NULL on failure.
+ * @return A new nix_eval_state_builder or NULL on failure. Call nix_eval_state_builder_free() when you're done.
  */
 nix_eval_state_builder * nix_eval_state_builder_new(nix_c_context * context, Store * store);
 
 /**
  * @brief Read settings from the ambient environment
+ * @ingroup libexpr_init
  *
  * Settings are sourced from environment variables and configuration files,
  * as documented in the Nix manual.
@@ -204,6 +220,7 @@ nix_err nix_eval_state_builder_load(nix_c_context * context, nix_eval_state_buil
 
 /**
  * @brief Set the lookup path for `<...>` expressions
+ * @ingroup libexpr_init
  *
  * @param[in] context Optional, stores error information
  * @param[in] builder The builder to modify.
@@ -214,18 +231,21 @@ nix_err nix_eval_state_builder_set_lookup_path(
 
 /**
  * @brief Create a new Nix language evaluator state
+ * @ingroup libexpr_init
  *
- * Remember to nix_eval_state_builder_free after building the state.
+ * The builder becomes unusable after this call. Remember to call nix_eval_state_builder_free()
+ * after building the state.
  *
  * @param[out] context Optional, stores error information
  * @param[in] builder The builder to use and free
- * @return A new Nix state or NULL on failure.
+ * @return A new Nix state or NULL on failure. Call nix_state_free() when you're done.
  * @see nix_eval_state_builder_new, nix_eval_state_builder_free
  */
 EvalState * nix_eval_state_build(nix_c_context * context, nix_eval_state_builder * builder);
 
 /**
  * @brief Free a nix_eval_state_builder
+ * @ingroup libexpr_init
  *
  * Does not fail.
  *
@@ -235,19 +255,21 @@ void nix_eval_state_builder_free(nix_eval_state_builder * builder);
 
 /**
  * @brief Create a new Nix language evaluator state
+ * @ingroup libexpr_init
  *
  * For more control, use nix_eval_state_builder
  *
  * @param[out] context Optional, stores error information
  * @param[in] lookupPath Null-terminated array of strings corresponding to entries in NIX_PATH.
  * @param[in] store The Nix store to use.
- * @return A new Nix state or NULL on failure.
+ * @return A new Nix state or NULL on failure. Call nix_state_free() when you're done.
  * @see nix_state_builder_new
  */
 EvalState * nix_state_create(nix_c_context * context, const char ** lookupPath, Store * store);
 
 /**
  * @brief Frees a Nix state.
+ * @ingroup libexpr_init
  *
  * Does not fail.
  *
@@ -256,6 +278,7 @@ EvalState * nix_state_create(nix_c_context * context, const char ** lookupPath,
 void nix_state_free(EvalState * state);
 
 /** @addtogroup GC
+ * @ingroup libexpr
  * @brief Reference counting and garbage collector operations
  *
  * The Nix language evaluator uses a garbage collector. To ease C interop, we implement
@@ -286,6 +309,9 @@ nix_err nix_gc_incref(nix_c_context * context, const void * object);
 /**
  * @brief Decrement the garbage collector reference counter for the given object
  *
+ * @deprecated We are phasing out the general nix_gc_decref() in favor of type-specified free functions, such as
+ * nix_value_decref().
+ *
  * We also provide typed `nix_*_decref` functions, which are
  *   - safer to use
  *   - easier to integrate when deriving bindings
@@ -314,12 +340,11 @@ void nix_gc_now();
  */
 void nix_gc_register_finalizer(void * obj, void * cd, void (*finalizer)(void * obj, void * cd));
 
-/** @} */
+/** @} */ // doxygen group GC
+
 // cffi end
 #ifdef __cplusplus
 }
 #endif
 
-/** @} */
-
 #endif // NIX_API_EXPR_H

src/libexpr-c/nix_api_external.h

@@ -2,11 +2,12 @@
 #define NIX_API_EXTERNAL_H
 /** @ingroup libexpr
  * @addtogroup Externals
- * @brief Deal with external values
+ * @brief Externals let Nix expressions work with foreign values that aren't part of the normal Nix value data model
  * @{
  */
 /** @file
  * @brief libexpr C bindings dealing with external values
+ * @see Externals
  */
 
 #include "nix_api_expr.h"
@@ -115,7 +116,7 @@ typedef struct NixCExternalValueDesc
      * @brief Try to compare two external values
      *
      * Optional, the default is always false.
-     * If the other object was not a Nix C external value, this comparison will
+     * If the other object was not a Nix C API external value, this comparison will
      * also return false
      * @param[in] self the void* passed to nix_create_external_value
      * @param[in] other the void* passed to the other object's
@@ -168,7 +169,7 @@ typedef struct NixCExternalValueDesc
 /**
  * @brief Create an external value, that can be given to nix_init_external
  *
- * Owned by the GC. Use nix_gc_decref when you're done with the pointer.
+ * Call nix_gc_decref() when you're done with the pointer.
  *
  * @param[out] context Optional, stores error information
  * @param[in] desc a NixCExternalValueDesc, you should keep this alive as long
@@ -180,10 +181,11 @@ typedef struct NixCExternalValueDesc
 ExternalValue * nix_create_external_value(nix_c_context * context, NixCExternalValueDesc * desc, void * v);
 
 /**
- * @brief Extract the pointer from a nix c external value.
+ * @brief Extract the pointer from a Nix C API external value.
  * @param[out] context Optional, stores error information
  * @param[in] b The external value
- * @returns The pointer, or null if the external value was not from nix c.
+ * @returns The pointer, valid while the external value is valid, or null if the external value was not from the Nix C
+ * API.
  * @see nix_get_external
  */
 void * nix_get_external_value_content(nix_c_context * context, ExternalValue * b);

src/libexpr-c/nix_api_value.h

@@ -1,9 +1,6 @@
 #ifndef NIX_API_VALUE_H
 #define NIX_API_VALUE_H
 
-/** @addtogroup libexpr
- * @{
- */
 /** @file
  * @brief libexpr C bindings dealing with values
  */
@@ -20,18 +17,89 @@ extern "C" {
 #endif
 // cffi start
 
+/** @defgroup value Value
+ * @ingroup libexpr
+ * @brief nix_value type and core operations for working with Nix values
+ * @see value_create
+ * @see value_extract
+ */
+
+/** @defgroup value_create Value Creation
+ * @ingroup libexpr
+ * @brief Functions for allocating and initializing Nix values
+ *
+ * Values are usually created with `nix_alloc_value` followed by `nix_init_*` functions.
+ * In primop callbacks, allocation is already done and only initialization is needed.
+ */
+
+/** @defgroup value_extract Value Extraction
+ * @ingroup libexpr
+ * @brief Functions for extracting data from Nix values
+ */
+
+/** @defgroup primops PrimOps and Builtins
+ * @ingroup libexpr
+ */
+
 // Type definitions
+/** @brief Represents the state of a Nix value
+ *
+ * Thunk values (NIX_TYPE_THUNK) change to their final, unchanging type when forced.
+ *
+ * @see https://nix.dev/manual/nix/latest/language/evaluation.html
+ * @enum ValueType
+ * @ingroup value
+ */
 typedef enum {
+    /** Unevaluated expression
+     *
+     * Thunks often contain an expression and closure, but may contain other
+     * representations too.
+     *
+     * Their state is mutable, unlike that of the other types.
+     */
     NIX_TYPE_THUNK,
+    /**
+     * A 64 bit signed integer.
+     */
     NIX_TYPE_INT,
+    /** @brief IEEE 754 double precision floating point number
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-float
+     */
     NIX_TYPE_FLOAT,
+    /** @brief Boolean true or false value
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-bool
+     */
     NIX_TYPE_BOOL,
+    /** @brief String value with context
+     *
+     * String content may contain arbitrary bytes, not necessarily UTF-8.
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-string
+     */
     NIX_TYPE_STRING,
+    /** @brief Filesystem path
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-path
+     */
     NIX_TYPE_PATH,
+    /** @brief Null value
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-null
+     */
     NIX_TYPE_NULL,
+    /** @brief Attribute set (key-value mapping)
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-attrs
+     */
     NIX_TYPE_ATTRS,
+    /** @brief Ordered list of values
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-list
+     */
     NIX_TYPE_LIST,
+    /** @brief Function (lambda or builtin)
+     * @see https://nix.dev/manual/nix/latest/language/types.html#type-function
+     */
     NIX_TYPE_FUNCTION,
+    /** @brief External value from C++ plugins or C API
+     * @see Externals
+     */
     NIX_TYPE_EXTERNAL
 } ValueType;
 
@@ -39,22 +107,41 @@ typedef enum {
 typedef struct nix_value nix_value;
 typedef struct EvalState EvalState;
 
+/** @deprecated Use nix_value instead */
 [[deprecated("use nix_value instead")]] typedef nix_value Value;
 
 // type defs
 /** @brief Stores an under-construction set of bindings
- * @ingroup value_manip
+ * @ingroup value_create
  *
- * Do not reuse.
+ * Each builder can only be used once. After calling nix_make_attrs(), the builder
+ * becomes invalid and must not be used again. Call nix_bindings_builder_free() to release it.
+ *
+ * Typical usage pattern:
+ * 1. Create with nix_make_bindings_builder()
+ * 2. Insert attributes with nix_bindings_builder_insert()
+ * 3. Create final attribute set with nix_make_attrs()
+ * 4. Free builder with nix_bindings_builder_free()
+ *
+ * @struct BindingsBuilder
  * @see nix_make_bindings_builder, nix_bindings_builder_free, nix_make_attrs
  * @see nix_bindings_builder_insert
  */
 typedef struct BindingsBuilder BindingsBuilder;
 
 /** @brief Stores an under-construction list
- * @ingroup value_manip
+ * @ingroup value_create
  *
- * Do not reuse.
+ * Each builder can only be used once. After calling nix_make_list(), the builder
+ * becomes invalid and must not be used again. Call nix_list_builder_free() to release it.
+ *
+ * Typical usage pattern:
+ * 1. Create with nix_make_list_builder()
+ * 2. Insert elements with nix_list_builder_insert()
+ * 3. Create final list with nix_make_list()
+ * 4. Free builder with nix_list_builder_free()
+ *
+ * @struct ListBuilder
  * @see nix_make_list_builder, nix_list_builder_free, nix_make_list
  * @see nix_list_builder_insert
  */
@@ -63,25 +150,28 @@ typedef struct ListBuilder ListBuilder;
 /** @brief PrimOp function
  * @ingroup primops
  *
- * Owned by the GC
- * @see nix_alloc_primop, nix_init_primop
+ * Can be released with nix_gc_decref() when necessary.
+ * @struct PrimOp
+ * @see nix_alloc_primop, nix_init_primop, nix_register_primop
  */
 typedef struct PrimOp PrimOp;
 /** @brief External Value
  * @ingroup Externals
  *
- * Owned by the GC
+ * Can be released with nix_gc_decref() when necessary.
+ * @struct ExternalValue
+ * @see nix_create_external_value, nix_init_external, nix_get_external
  */
 typedef struct ExternalValue ExternalValue;
 
 /** @brief String without placeholders, and realised store paths
+ * @struct nix_realised_string
+ * @see nix_string_realise, nix_realised_string_free
  */
 typedef struct nix_realised_string nix_realised_string;
 
-/** @defgroup primops Adding primops
- * @{
- */
 /** @brief Function pointer for primops
+ * @ingroup primops
  *
  * When you want to return an error, call nix_set_err_msg(context, NIX_ERR_UNKNOWN, "your error message here").
  *
@@ -97,9 +187,9 @@ typedef void (*PrimOpFun)(
     void * user_data, nix_c_context * context, EvalState * state, nix_value ** args, nix_value * ret);
 
 /** @brief Allocate a PrimOp
+ * @ingroup primops
  *
- * Owned by the garbage collector.
- * Use nix_gc_decref() when you're done with the returned PrimOp.
+ * Call nix_gc_decref() when you're done with the returned PrimOp.
  *
  * @param[out] context Optional, stores error information
  * @param[in] fun callback
@@ -121,35 +211,38 @@ PrimOp * nix_alloc_primop(
     void * user_data);
 
 /** @brief add a primop to the `builtins` attribute set
+ * @ingroup primops
  *
  * Only applies to States created after this call.
  *
- * Moves your PrimOp content into the global evaluator
- * registry, meaning your input PrimOp pointer is no longer usable.
- * You are free to remove your references to it,
- * after which it will be garbage collected.
+ * Moves your PrimOp content into the global evaluator registry, meaning
+ * your input PrimOp pointer becomes invalid. The PrimOp must not be used
+ * with nix_init_primop() before or after this call, as this would cause
+ * undefined behavior.
+ * You must call nix_gc_decref() on the original PrimOp pointer
+ * after this call to release your reference.
  *
  * @param[out] context Optional, stores error information
- * @return primop, or null in case of errors
- *
+ * @param[in] primOp PrimOp to register
+ * @return error code, NIX_OK on success
  */
 nix_err nix_register_primop(nix_c_context * context, PrimOp * primOp);
-/** @} */
 
 // Function prototypes
 
 /** @brief Allocate a Nix value
+ * @ingroup value_create
  *
- * Owned by the GC. Use nix_gc_decref() when you're done with the pointer
+ * Call nix_value_decref() when you're done with the pointer
  * @param[out] context Optional, stores error information
  * @param[in] state nix evaluator state
  * @return value, or null in case of errors
- *
  */
 nix_value * nix_alloc_value(nix_c_context * context, EvalState * state);
 
 /**
  * @brief Increment the garbage collector reference counter for the given `nix_value`.
+ * @ingroup value
  *
  * The Nix language evaluator C API keeps track of alive objects by reference counting.
  * When you're done with a refcounted pointer, call nix_value_decref().
@@ -161,21 +254,19 @@ nix_err nix_value_incref(nix_c_context * context, nix_value * value);
 
 /**
  * @brief Decrement the garbage collector reference counter for the given object
+ * @ingroup value
+ *
+ * When the counter reaches zero, the `nix_value` object becomes invalid.
+ * The data referenced by `nix_value` may not be deallocated until the memory
+ * garbage collector has run, but deallocation is not guaranteed.
  *
  * @param[out] context Optional, stores error information
  * @param[in] value The object to stop referencing
  */
 nix_err nix_value_decref(nix_c_context * context, nix_value * value);
 
-/** @addtogroup value_manip Manipulating values
- * @brief Functions to inspect and change Nix language values, represented by nix_value.
- * @{
- */
-/** @anchor getters
- * @name Getters
- */
-/**@{*/
 /** @brief Get value type
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @return type of nix value
@@ -183,14 +274,15 @@ nix_err nix_value_decref(nix_c_context * context, nix_value * value);
 ValueType nix_get_type(nix_c_context * context, const nix_value * value);
 
 /** @brief Get type name of value as defined in the evaluator
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
- * @return type name, owned string
- * @todo way to free the result
+ * @return type name string, free with free()
  */
 const char * nix_get_typename(nix_c_context * context, const nix_value * value);
 
 /** @brief Get boolean value
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @return true or false, error info via context
@@ -198,6 +290,7 @@ const char * nix_get_typename(nix_c_context * context, const nix_value * value);
 bool nix_get_bool(nix_c_context * context, const nix_value * value);
 
 /** @brief Get the raw string
+ * @ingroup value_extract
  *
  * This may contain placeholders.
  *
@@ -205,21 +298,21 @@ bool nix_get_bool(nix_c_context * context, const nix_value * value);
  * @param[in] value Nix value to inspect
  * @param[in] callback Called with the string value.
  * @param[in] user_data optional, arbitrary data, passed to the callback when it's called.
- * @return string
  * @return error code, NIX_OK on success.
  */
 nix_err
 nix_get_string(nix_c_context * context, const nix_value * value, nix_get_string_callback callback, void * user_data);
 
 /** @brief Get path as string
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
- * @return string, if the type is NIX_TYPE_PATH
- * @return NULL in case of error.
+ * @return string valid while value is valid, NULL in case of error
  */
 const char * nix_get_path_string(nix_c_context * context, const nix_value * value);
 
 /** @brief Get the length of a list
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @return length of list, error info via context
@@ -227,6 +320,7 @@ const char * nix_get_path_string(nix_c_context * context, const nix_value * valu
 unsigned int nix_get_list_size(nix_c_context * context, const nix_value * value);
 
 /** @brief Get the element count of an attrset
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @return attrset element count, error info via context
@@ -234,6 +328,7 @@ unsigned int nix_get_list_size(nix_c_context * context, const nix_value * value)
 unsigned int nix_get_attrs_size(nix_c_context * context, const nix_value * value);
 
 /** @brief Get float value in 64 bits
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @return float contents, error info via context
@@ -241,6 +336,7 @@ unsigned int nix_get_attrs_size(nix_c_context * context, const nix_value * value
 double nix_get_float(nix_c_context * context, const nix_value * value);
 
 /** @brief Get int value
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @return int contents, error info via context
@@ -248,15 +344,18 @@ double nix_get_float(nix_c_context * context, const nix_value * value);
 int64_t nix_get_int(nix_c_context * context, const nix_value * value);
 
 /** @brief Get external reference
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
- * @return reference to external, NULL in case of error
+ * @return reference valid while value is valid. Call nix_gc_incref() if you need it to live longer, then only in that
+ * case call nix_gc_decref() when done. NULL in case of error
  */
 ExternalValue * nix_get_external(nix_c_context * context, nix_value * value);
 
 /** @brief Get the ix'th element of a list
+ * @ingroup value_extract
  *
- * Owned by the GC. Use nix_gc_decref when you're done with the pointer
+ * Call nix_value_decref() when you're done with the pointer
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @param[in] state nix evaluator state
@@ -266,11 +365,12 @@ ExternalValue * nix_get_external(nix_c_context * context, nix_value * value);
 nix_value * nix_get_list_byidx(nix_c_context * context, const nix_value * value, EvalState * state, unsigned int ix);
 
 /** @brief Get the ix'th element of a list without forcing evaluation of the element
+ * @ingroup value_extract
  *
  * Returns the list element without forcing its evaluation, allowing access to lazy values.
  * The list value itself must already be evaluated.
  *
- * Owned by the GC. Use nix_gc_decref when you're done with the pointer
+ * Call nix_value_decref() when you're done with the pointer
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect (must be an evaluated list)
  * @param[in] state nix evaluator state
@@ -281,8 +381,9 @@ nix_value *
 nix_get_list_byidx_lazy(nix_c_context * context, const nix_value * value, EvalState * state, unsigned int ix);
 
 /** @brief Get an attr by name
+ * @ingroup value_extract
  *
- * Use nix_gc_decref when you're done with the pointer
+ * Call nix_value_decref() when you're done with the pointer
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @param[in] state nix evaluator state
@@ -292,11 +393,12 @@ nix_get_list_byidx_lazy(nix_c_context * context, const nix_value * value, EvalSt
 nix_value * nix_get_attr_byname(nix_c_context * context, const nix_value * value, EvalState * state, const char * name);
 
 /** @brief Get an attribute value by attribute name, without forcing evaluation of the attribute's value
+ * @ingroup value_extract
  *
  * Returns the attribute value without forcing its evaluation, allowing access to lazy values.
  * The attribute set value itself must already be evaluated.
  *
- * Use nix_gc_decref when you're done with the pointer
+ * Call nix_value_decref() when you're done with the pointer
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect (must be an evaluated attribute set)
  * @param[in] state nix evaluator state
@@ -307,6 +409,7 @@ nix_value *
 nix_get_attr_byname_lazy(nix_c_context * context, const nix_value * value, EvalState * state, const char * name);
 
 /** @brief Check if an attribute name exists on a value
+ * @ingroup value_extract
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @param[in] state nix evaluator state
@@ -316,6 +419,7 @@ nix_get_attr_byname_lazy(nix_c_context * context, const nix_value * value, EvalS
 bool nix_has_attr_byname(nix_c_context * context, const nix_value * value, EvalState * state, const char * name);
 
 /** @brief Get an attribute by index
+ * @ingroup value_extract
  *
  * Also gives you the name.
  *
@@ -329,18 +433,19 @@ bool nix_has_attr_byname(nix_c_context * context, const nix_value * value, EvalS
  * lexicographic order by Unicode scalar value for valid UTF-8). We recommend
  * applying this same ordering for consistency.
  *
- * Use nix_gc_decref when you're done with the pointer
+ * Call nix_value_decref() when you're done with the pointer
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @param[in] state nix evaluator state
  * @param[in] i attribute index
- * @param[out] name will store a pointer to the attribute name
+ * @param[out] name will store a pointer to the attribute name, valid until state is freed
  * @return value, NULL in case of errors
  */
 nix_value *
 nix_get_attr_byidx(nix_c_context * context, nix_value * value, EvalState * state, unsigned int i, const char ** name);
 
 /** @brief Get an attribute by index, without forcing evaluation of the attribute's value
+ * @ingroup value_extract
  *
  * Also gives you the name.
  *
@@ -357,18 +462,19 @@ nix_get_attr_byidx(nix_c_context * context, nix_value * value, EvalState * state
  * lexicographic order by Unicode scalar value for valid UTF-8). We recommend
  * applying this same ordering for consistency.
  *
- * Use nix_gc_decref when you're done with the pointer
+ * Call nix_value_decref() when you're done with the pointer
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect (must be an evaluated attribute set)
  * @param[in] state nix evaluator state
  * @param[in] i attribute index
- * @param[out] name will store a pointer to the attribute name
+ * @param[out] name will store a pointer to the attribute name, valid until state is freed
  * @return value, NULL in case of errors
  */
 nix_value * nix_get_attr_byidx_lazy(
     nix_c_context * context, nix_value * value, EvalState * state, unsigned int i, const char ** name);
 
 /** @brief Get an attribute name by index
+ * @ingroup value_extract
  *
  * Returns the attribute name without forcing evaluation of the attribute's value.
  *
@@ -382,16 +488,14 @@ nix_value * nix_get_attr_byidx_lazy(
  * lexicographic order by Unicode scalar value for valid UTF-8). We recommend
  * applying this same ordering for consistency.
  *
- * Owned by the nix EvalState
  * @param[out] context Optional, stores error information
  * @param[in] value Nix value to inspect
  * @param[in] state nix evaluator state
  * @param[in] i attribute index
- * @return name, NULL in case of errors
+ * @return name string valid until state is freed, NULL in case of errors
  */
 const char * nix_get_attr_name_byidx(nix_c_context * context, nix_value * value, EvalState * state, unsigned int i);
 
-/**@}*/
 /** @name Initializers
  *
  * Values are typically "returned" by initializing already allocated memory that serves as the return value.
@@ -401,6 +505,7 @@ const char * nix_get_attr_name_byidx(nix_c_context * context, nix_value * value,
  */
 /**@{*/
 /** @brief Set boolean value
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] b the boolean value
@@ -409,6 +514,7 @@ const char * nix_get_attr_name_byidx(nix_c_context * context, nix_value * value,
 nix_err nix_init_bool(nix_c_context * context, nix_value * value, bool b);
 
 /** @brief Set a string
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] str the string, copied
@@ -417,6 +523,7 @@ nix_err nix_init_bool(nix_c_context * context, nix_value * value, bool b);
 nix_err nix_init_string(nix_c_context * context, nix_value * value, const char * str);
 
 /** @brief Set a path
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] str the path string, copied
@@ -425,6 +532,7 @@ nix_err nix_init_string(nix_c_context * context, nix_value * value, const char *
 nix_err nix_init_path_string(nix_c_context * context, EvalState * s, nix_value * value, const char * str);
 
 /** @brief Set a float
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] d the float, 64-bits
@@ -433,6 +541,7 @@ nix_err nix_init_path_string(nix_c_context * context, EvalState * s, nix_value *
 nix_err nix_init_float(nix_c_context * context, nix_value * value, double d);
 
 /** @brief Set an int
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] i the int
@@ -441,6 +550,7 @@ nix_err nix_init_float(nix_c_context * context, nix_value * value, double d);
 
 nix_err nix_init_int(nix_c_context * context, nix_value * value, int64_t i);
 /** @brief Set null
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @return error code, NIX_OK on success.
@@ -448,6 +558,7 @@ nix_err nix_init_int(nix_c_context * context, nix_value * value, int64_t i);
 nix_err nix_init_null(nix_c_context * context, nix_value * value);
 
 /** @brief Set the value to a thunk that will perform a function application when needed.
+ * @ingroup value_create
  *
  * Thunks may be put into attribute sets and lists to perform some computation lazily; on demand.
  * However, note that in some places, a thunk must not be returned, such as in the return value of a PrimOp.
@@ -464,6 +575,7 @@ nix_err nix_init_null(nix_c_context * context, nix_value * value);
 nix_err nix_init_apply(nix_c_context * context, nix_value * value, nix_value * fn, nix_value * arg);
 
 /** @brief Set an external value
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] val the external value to set. Will be GC-referenced by the value.
@@ -472,18 +584,25 @@ nix_err nix_init_apply(nix_c_context * context, nix_value * value, nix_value * f
 nix_err nix_init_external(nix_c_context * context, nix_value * value, ExternalValue * val);
 
 /** @brief Create a list from a list builder
+ * @ingroup value_create
+ *
+ * After this call, the list builder becomes invalid and cannot be used again.
+ * The only necessary next step is to free it with nix_list_builder_free().
+ *
  * @param[out] context Optional, stores error information
- * @param[in] list_builder list builder to use. Make sure to unref this afterwards.
+ * @param[in] list_builder list builder to use
  * @param[out] value Nix value to modify
  * @return error code, NIX_OK on success.
+ * @see nix_list_builder_free
  */
 nix_err nix_make_list(nix_c_context * context, ListBuilder * list_builder, nix_value * value);
 
 /** @brief Create a list builder
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[in] state nix evaluator state
  * @param[in] capacity how many bindings you'll add. Don't exceed.
- * @return owned reference to a list builder. Make sure to unref when you're done.
+ * @return list builder. Call nix_list_builder_free() when you're done.
  */
 ListBuilder * nix_make_list_builder(nix_c_context * context, EvalState * state, size_t capacity);
 
@@ -505,14 +624,21 @@ nix_list_builder_insert(nix_c_context * context, ListBuilder * list_builder, uns
 void nix_list_builder_free(ListBuilder * list_builder);
 
 /** @brief Create an attribute set from a bindings builder
+ * @ingroup value_create
+ *
+ * After this call, the bindings builder becomes invalid and cannot be used again.
+ * The only necessary next step is to free it with nix_bindings_builder_free().
+ *
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
- * @param[in] b bindings builder to use. Make sure to unref this afterwards.
+ * @param[in] b bindings builder to use
  * @return error code, NIX_OK on success.
+ * @see nix_bindings_builder_free
  */
 nix_err nix_make_attrs(nix_c_context * context, nix_value * value, BindingsBuilder * b);
 
 /** @brief Set primop
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] op primop, will be gc-referenced by the value
@@ -521,6 +647,7 @@ nix_err nix_make_attrs(nix_c_context * context, nix_value * value, BindingsBuild
  */
 nix_err nix_init_primop(nix_c_context * context, nix_value * value, PrimOp * op);
 /** @brief Copy from another value
+ * @ingroup value_create
  * @param[out] context Optional, stores error information
  * @param[out] value Nix value to modify
  * @param[in] source value to copy from
@@ -533,8 +660,7 @@ nix_err nix_copy_value(nix_c_context * context, nix_value * value, const nix_val
  * @param[out] context Optional, stores error information
  * @param[in] state nix evaluator state
  * @param[in] capacity how many bindings you'll add. Don't exceed.
-* @return owned reference to a bindings builder. Make sure to unref when you're
-done.
+ * @return bindings builder. Call nix_bindings_builder_free() when you're done.
  */
 BindingsBuilder * nix_make_bindings_builder(nix_c_context * context, EvalState * state, size_t capacity);
 
@@ -554,7 +680,6 @@ nix_bindings_builder_insert(nix_c_context * context, BindingsBuilder * builder,
  * @param[in] builder the builder to free
  */
 void nix_bindings_builder_free(BindingsBuilder * builder);
-/**@}*/
 
 /** @brief Realise a string context.
  *
@@ -571,13 +696,13 @@ void nix_bindings_builder_free(BindingsBuilder * builder);
  * @param[in] isIFD If true, disallow derivation outputs if setting `allow-import-from-derivation` is false.
                     You should set this to true when this call is part of a primop.
                     You should set this to false when building for your application's purpose.
- * @return NULL if failed, are a new nix_realised_string, which must be freed with nix_realised_string_free
+ * @return NULL if failed, or a new nix_realised_string, which must be freed with nix_realised_string_free
  */
 nix_realised_string * nix_string_realise(nix_c_context * context, EvalState * state, nix_value * value, bool isIFD);
 
 /** @brief Start of the string
  * @param[in] realised_string
- * @return pointer to the start of the string. It may not be null-terminated.
+ * @return pointer to the start of the string, valid until realised_string is freed. It may not be null-terminated.
  */
 const char * nix_realised_string_get_buffer_start(nix_realised_string * realised_string);
 
@@ -596,7 +721,7 @@ size_t nix_realised_string_get_store_path_count(nix_realised_string * realised_s
 /** @brief Get a store path. The store paths are stored in an arbitrary order.
  * @param[in] realised_string
  * @param[in] index index of the store path, must be less than the count
- * @return store path
+ * @return store path valid until realised_string is freed
  */
 const StorePath * nix_realised_string_get_store_path(nix_realised_string * realised_string, size_t index);
 
@@ -610,5 +735,4 @@ void nix_realised_string_free(nix_realised_string * realised_string);
 }
 #endif
 
-/** @} */
 #endif // NIX_API_VALUE_H

src/libutil-c/nix_api_util.h

@@ -155,6 +155,8 @@ typedef struct nix_c_context nix_c_context;
 /**
  * @brief Called to get the value of a string owned by Nix.
  *
+ * The `start` data is borrowed and the function must not assume that the buffer persists after it returns.
+ *
  * @param[in] start the string to copy.
  * @param[in] n the string length.
  * @param[in] user_data optional, arbitrary data, passed to the nix_get_string_callback when it's called.