From e74d6c1b3d13f68ae78546f5372436bb12095d26 Mon Sep 17 00:00:00 2001
From: Yorick van Pelt <yorick@yorickvanpelt.nl>
Date: Thu, 3 Aug 2023 15:45:39 +0200
Subject: [PATCH] nix_api_expr: document nix_value_force

---
 src/libexpr/nix_api_expr.h | 11 +++++++++++
 src/libutil/nix_api_util.h |  3 ++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/libexpr/nix_api_expr.h b/src/libexpr/nix_api_expr.h
index 1211c587f..94eaa5a6c 100644
--- a/src/libexpr/nix_api_expr.h
+++ b/src/libexpr/nix_api_expr.h
@@ -97,9 +97,15 @@ nix_err nix_value_call(nix_c_context *context, State *state, Value *fn,
 /**
  * @brief Forces the evaluation of a Nix value.
  *
+ * The Nix interpreter is lazy, and not-yet-evaluated Values can be
+ * of type NIX_TYPE_THUNK instead of their actual value.
+ *
+ * This function converts Values into their final type.
+ *
  * @param[out] context Optional, stores error information
  * @param[in] state The state of the evaluation.
  * @param[in,out] value The Nix value to force.
+ * @post values is not of type NIX_TYPE_THUNK
  * @return NIX_OK if the force operation was successful, an error code
  * otherwise.
  */
@@ -108,6 +114,11 @@ nix_err nix_value_force(nix_c_context *context, State *state, Value *value);
 /**
  * @brief Forces the deep evaluation of a Nix value.
  *
+ * Recursively calls nix_value_force
+ *
+ * @see nix_value_force
+ * @warning Calling this function on a recursive data structure will cause a
+ * stack overflow.
  * @param[out] context Optional, stores error information
  * @param[in] state The state of the evaluation.
  * @param[in,out] value The Nix value to force.
diff --git a/src/libutil/nix_api_util.h b/src/libutil/nix_api_util.h
index 98c837a84..4a7f6c4cd 100644
--- a/src/libutil/nix_api_util.h
+++ b/src/libutil/nix_api_util.h
@@ -23,7 +23,8 @@ extern "C" {
  * @brief Dealing with errors from the Nix side
  *
  * To handle errors that can be returned from the Nix API,
- * a nix_c_context can be passed to any function that potentially returns an error.
+ * a nix_c_context can be passed to any function that potentially returns an
+ * error.
  *
  * Error information will be stored in this context, and can be retrieved
  * using nix_err_code and nix_err_msg.