nix_api_expr, nix_api_util: slightly improve documentation

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);
+ *    State* state = nix_state_create(NULL, NULL, store); // empty nix path
-*Value *value = nix_alloc_value(NULL, state);
+ *    Value *value = nix_alloc_value(NULL, state);
-**nix_expr_eval_from_string(NULL, state, "builtins.nixVersion", ".", value);
+ *
-*nix_value_force(NULL, state, value);
+ *    nix_expr_eval_from_string(NULL, state, "builtins.nixVersion", ".", value);
-*printf("nix version: %s\n", nix_get_string(NULL, value));
+ *    nix_value_force(NULL, state, value);
-**nix_gc_decref(NULL, value);
+ *    printf("nix version: %s\n", nix_get_string(NULL, value));
-*nix_state_free(state);
+ *
-*nix_store_unref(store);
+ *    nix_gc_decref(NULL, value);
-*return 0;
+ *    nix_state_free(state);
-*
+ *    nix_store_unref(store);
-}
+ *    return 0;
-*@endcode *@{* /
+ *    }
+ * @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
+// Type definitions
-                 /**
+/**
-                  * @brief Represents a nix evaluator state.
+ * @brief Represents a nix evaluator state.
-                  *
+ *
-                  * Multiple can be created for multi-threaded
+ * Multiple can be created for multi-threaded
-                  * operation.
+ * operation.
-                  * @struct State
+ * @struct State
-                  */
+ */
-                 typedef struct State State; // nix::EvalState
+typedef struct State State; // nix::EvalState
 /**
  * @brief Represents a nix value.
  *

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
+ * To handle errors that can be returned from the Nix API,
- * nix_c_context can be passed 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, 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
+ * Passed as a first parameter to functions that can fail, to store error
- * information. Optional wherever it is used, passing NULL will throw a C++
+ * information.
- * exception instead. The first field is a nix_err, that can be read directly to
+ *
- * check for errors.
+ * 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).