C API: clarify some documentation

This commit is contained in:
Yorick van Pelt 2023-08-28 16:42:59 +02:00 committed by José Luis Lafuente
parent 5d82d6e733
commit 9d380c0f76
No known key found for this signature in database
GPG key ID: 8A3455EBE455489A
5 changed files with 22 additions and 19 deletions

View file

@ -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 can be called multiple times.
* This function must be called at least once,
* 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.

View file

@ -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] args list of arguments
* @param[out] v return value
* @param[in] pos Call position, opaque index into the state's position table.
* @param[in] args list of arguments. Note that these can be thunks and should be forced using nix_value_force before use.
* @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

View file

@ -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());
}
}
}

View file

@ -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));
/**

View file

@ -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
initialization. In particular, these plugins may construct static
instances of RegisterPrimOp to add new primops or constants to the
be dlopened by Nix. If they contain the symbol `nix_plugin_entry()`,
this symbol will be called. Alternatively, they can affect execution
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