From e58a9384c67eb8b229c309b86580a3f778535ce0 Mon Sep 17 00:00:00 2001
From: Yorick van Pelt <yorick@yorickvanpelt.nl>
Date: Mon, 31 Jul 2023 09:02:28 +0200
Subject: [PATCH] nix_api_expr, nix_api_util: slightly improve documentation

---
 src/libexpr/nix_api_expr.h | 49 ++++++++++++++++++++------------------
 src/libutil/nix_api_util.h | 21 ++++++++++------
 2 files changed, 40 insertions(+), 30 deletions(-)

diff --git a/src/libexpr/nix_api_expr.h b/src/libexpr/nix_api_expr.h
index f67a3d13f..1211c587f 100644
--- a/src/libexpr/nix_api_expr.h
+++ b/src/libexpr/nix_api_expr.h
@@ -9,18 +9,21 @@
  *    nix_libexpr_init(NULL);
  *
  *    Store* store = nix_store_open(NULL, "dummy", NULL);
- *    State* state = nix_state_create(NULL, NULL /* empty NIX_PATH */, store);
-*Value *value = nix_alloc_value(NULL, state);
-**nix_expr_eval_from_string(NULL, state, "builtins.nixVersion", ".", value);
-*nix_value_force(NULL, state, value);
-*printf("nix version: %s\n", nix_get_string(NULL, value));
-**nix_gc_decref(NULL, value);
-*nix_state_free(state);
-*nix_store_unref(store);
-*return 0;
-*
-}
-*@endcode *@{* /
+ *    State* state = nix_state_create(NULL, NULL, store); // empty nix path
+ *    Value *value = nix_alloc_value(NULL, state);
+ *
+ *    nix_expr_eval_from_string(NULL, state, "builtins.nixVersion", ".", value);
+ *    nix_value_force(NULL, state, value);
+ *    printf("nix version: %s\n", nix_get_string(NULL, value));
+ *
+ *    nix_gc_decref(NULL, value);
+ *    nix_state_free(state);
+ *    nix_store_unref(store);
+ *    return 0;
+ *    }
+ * @endcode
+ * @{
+ */
 /** @file
  * @brief Main entry for the libexpr C bindings
  */
@@ -29,19 +32,19 @@
 #include "nix_api_util.h"
 
 #ifdef __cplusplus
-             extern "C" {
+extern "C" {
 #endif
-                 // cffi start
+// cffi start
 
-                 // Type definitions
-                 /**
-                  * @brief Represents a nix evaluator state.
-                  *
-                  * Multiple can be created for multi-threaded
-                  * operation.
-                  * @struct State
-                  */
-                 typedef struct State State; // nix::EvalState
+// Type definitions
+/**
+ * @brief Represents a nix evaluator state.
+ *
+ * Multiple can be created for multi-threaded
+ * operation.
+ * @struct State
+ */
+typedef struct State State; // nix::EvalState
 /**
  * @brief Represents a nix value.
  *
diff --git a/src/libutil/nix_api_util.h b/src/libutil/nix_api_util.h
index 63854e4d8..98c837a84 100644
--- a/src/libutil/nix_api_util.h
+++ b/src/libutil/nix_api_util.h
@@ -22,11 +22,11 @@ extern "C" {
 /** @defgroup errors Handling errors
  * @brief Dealing with errors from the Nix side
  *
- * To handle errors that can be returned from the Nix API
- * nix_c_context can be passed any function that potentially returns an error.
+ * 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.
  *
  * Error information will be stored in this context, and can be retrieved
- * using nix_err_code, nix_err_msg.
+ * using nix_err_code and nix_err_msg.
  *
  * Passing NULL instead will cause the API to throw C++ errors.
  *
@@ -101,10 +101,17 @@ typedef int nix_err;
  * @brief This object stores error state.
  * @struct nix_c_context
  *
- * Passed as a first parameter to C functions that can fail, will store error
- * information. Optional wherever it is used, passing NULL will throw a C++
- * exception instead. The first field is a nix_err, that can be read directly to
- * check for errors.
+ * Passed as a first parameter to functions that can fail, to store error
+ * information.
+ *
+ * Optional wherever it can be used, passing NULL instead will throw a C++
+ * exception.
+ *
+ * The struct is laid out so that it can also be cast to nix_err* to inspect
+ * directly:
+ * @code{.c}
+ * assert(*(nix_err*)ctx == NIX_OK);
+ * @endcode
  * @note These can be reused between different function calls,
  *  but make sure not to use them for multiple calls simultaneously (which can
  * happen in callbacks).