C API: clarify some documentation

src/libexpr/c/nix_api_expr.h

@@ -59,8 +59,9 @@ typedef void Value; // nix::Value
 /**
  * @brief Initialize the Nix language evaluator.
  *
- * This function should be called before creating a State.
+ * This function must be called at least once,
- * This function can be called multiple times.
+ * at some point before constructing a State for the first time.
+ * This function can be called multiple times, and is idempotent.
  *
  * @param[out] context Optional, stores error information
  * @return NIX_OK if the initialization was successful, an error code otherwise.
@@ -106,7 +107,8 @@ nix_err nix_value_call(nix_c_context *context, State *state, Value *fn,
  *
  * @note You don't need this function for basic API usage, since all functions
  * that return a value call it for you. The only place you will see a
- * NIX_TYPE_THUNK is in the primop callback.
+ * NIX_TYPE_THUNK is in the arguments that are passed to a PrimOp function
+ * you supplied to nix_alloc_primop.
  *
  * @param[out] context Optional, stores error information
  * @param[in] state The state of the evaluation.

src/libexpr/c/nix_api_value.h

@@ -66,12 +66,12 @@ typedef struct ExternalValue ExternalValue;
  */
 /** @brief Function pointer for primops
  * @param[in] state Evaluator state
- * @param[in] pos position of function call
+ * @param[in] pos Call position, opaque index into the state's position table.
- * @param[in] args list of arguments
+ * @param[in] args list of arguments. Note that these can be thunks and should be forced using nix_value_force before use.
- * @param[out] v return value
+ * @param[out] ret return value
  * @see nix_alloc_primop, nix_set_primop
  */
-typedef void (*PrimOpFun)(State *state, int pos, Value **args, Value *v);
+typedef void (*PrimOpFun)(State *state, int pos, Value **args, Value *ret);
 
 /** @brief Allocate a PrimOp
  *
@@ -80,9 +80,9 @@ typedef void (*PrimOpFun)(State *state, int pos, Value **args, Value *v);
  *
  * @param[out] context Optional, stores error information
  * @param[in] fun callback
- * @param[in] arity expected amount of function arguments
+ * @param[in] arity expected number of function arguments
  * @param[in] name function name
- * @param[in] args array of argument names
+ * @param[in] args array of argument names, NULL-terminated
  * @param[in] doc optional, documentation for this primop
  * @return primop, or null in case of errors
  * @see nix_set_primop

src/libstore/c/nix_api_store.cc

@@ -103,7 +103,7 @@ StorePath *nix_store_parse_path(nix_c_context *context, Store *store,
 
 nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
                         void *userdata,
-                        void (*iter)(void *userdata, const char *,
+                        void (*callback)(void *userdata, const char *,
                                      const char *)) {
   if (context)
     context->last_err_code = NIX_OK;
@@ -114,11 +114,11 @@ nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
             .outputs = nix::OutputsSpec::All{},
         },
     });
-    if (iter) {
+    if (callback) {
       for (auto &[outputName, outputPath] :
            store->ptr->queryDerivationOutputMap(path->path)) {
         auto op = store->ptr->printStorePath(outputPath);
-        iter(userdata, outputName.c_str(), op.c_str());
+        callback(userdata, outputName.c_str(), op.c_str());
       }
     }
   }

src/libstore/c/nix_api_store.h

@@ -36,7 +36,7 @@ typedef struct StorePath StorePath;
 nix_err nix_libstore_init(nix_c_context *context);
 
 /**
- * @brief Loads plugins specified in the settings
+ * @brief Loads the plugins specified in Nix's plugin-files setting.
  *
  * Call this once, after calling your desired init functions and setting
  * relevant settings.
@@ -111,17 +111,17 @@ bool nix_store_is_valid_path(nix_c_context *context, Store *store,
 /**
  * @brief Realise a Nix store path
  *
- * Blocking, calls cb once for each built output
+ * Blocking, calls callback once for each realisedoutput
  *
  * @param[out] context Optional, stores error information
  * @param[in] store Nix Store reference
  * @param[in] path Path to build
  * @param[in] userdata data to pass to every callback invocation
- * @param[in] cb called for every built output
+ * @param[in] callback called for every realised output
  */
 nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
                         void *userdata,
-                        void (*cb)(void *userdata, const char *outname,
+                        void (*callback)(void *userdata, const char *outname,
                                    const char *out));
 
 /**

src/libstore/globals.hh

@@ -1156,9 +1156,10 @@ public:
         this, {}, "plugin-files",
         R"(
           A list of plugin files to be loaded by Nix. Each of these files will
-          be dlopened by Nix, allowing them to affect execution through static
+          be dlopened by Nix. If they contain the symbol `nix_plugin_entry()`,
-          initialization. In particular, these plugins may construct static
+          this symbol will be called. Alternatively, they can affect execution
-          instances of RegisterPrimOp to add new primops or constants to the
+          through static initialization. In particular, these plugins may construct
+          static instances of RegisterPrimOp to add new primops or constants to the
           expression language, RegisterStoreImplementation to add new store
           implementations, RegisterCommand to add new subcommands to the `nix`
           command, and RegisterSetting to add new nix config settings. See the