external-api-doc: introduce and improve documentation

src/libexpr/nix_api_expr.h

@@ -1,5 +1,26 @@
 #ifndef NIX_API_EXPR_H
 #define NIX_API_EXPR_H
+/** @defgroup libexpr libexpr
+ * @brief Bindings to the Nix evaluator
+ *
+ * Example (without error handling):
+ * @code{.c}
+ * int main() {
+ *    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 *@{* /
 /** @file
  * @brief Main entry for the libexpr C bindings
  */
@@ -8,22 +29,25 @@
 #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.
- */
-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.
  *
  * Owned by the GC.
+ * @struct Value
+ * @see value_manip
  */
 typedef void Value; // nix::Value
 
@@ -110,23 +134,36 @@ State *nix_state_create(nix_c_context *context, const char **searchPath,
  */
 void nix_state_free(State *state);
 
+/** @addtogroup GC
+ * @brief Reference counting and garbage collector operations
+ *
+ * Nix's evaluator uses a garbage collector. To ease C interop, we implement
+ * a reference counting scheme, where objects will be deallocated
+ * when there are no references from the Nix side, and the reference count kept
+ * by the C API reaches `0`.
+ *
+ * Functions returning a garbage-collected object will automatically increase
+ * the refcount for you. You should make sure to call `nix_gc_decref` when
+ * you're done.
+ * @{
+ */
 /**
  * @brief Increase the GC refcount.
  *
  * The nix C api keeps alive objects by refcounting.
  * When you're done with a refcounted pointer, call nix_gc_decref.
  *
- * Does not fail
- *
+ * @param[out] context Optional, stores error information
  * @param[in] object The object to keep alive
  */
-nix_err nix_gc_incref(nix_c_context *, const void *);
+nix_err nix_gc_incref(nix_c_context *context, const void *object);
 /**
  * @brief Decrease the GC refcount
  *
+ * @param[out] context Optional, stores error information
  * @param[in] object The object to stop referencing
  */
-nix_err nix_gc_decref(nix_c_context *, const void *);
+nix_err nix_gc_decref(nix_c_context *context, const void *object);
 
 /**
  * @brief Trigger the garbage collector manually
@@ -147,9 +184,12 @@ void nix_gc_now();
 void nix_gc_register_finalizer(void *obj, void *cd,
                                void (*finalizer)(void *obj, void *cd));
 
+/** @} */
 // cffi end
 #ifdef __cplusplus
 }
 #endif
 
+/** @} */
+
 #endif // NIX_API_EXPR_H

src/libexpr/nix_api_external.h

@@ -1,5 +1,10 @@
 #ifndef NIX_API_EXTERNAL_H
 #define NIX_API_EXTERNAL_H
+/** @ingroup libexpr
+ * @addtogroup Externals
+ * @brief Deal with external values
+ * @{
+ */
 /** @file
  * @brief libexpr C bindings dealing with external values
  */
@@ -184,5 +189,6 @@ void *nix_get_external_value_content(nix_c_context *context, ExternalValue *b);
 #ifdef __cplusplus
 }
 #endif
+/** @} */
 
 #endif // NIX_API_EXTERNAL_H

src/libexpr/nix_api_value.h

@@ -1,6 +1,9 @@
 #ifndef NIX_API_VALUE_H
 #define NIX_API_VALUE_H
 
+/** @addtogroup libexpr
+ * @{
+ */
 /** @file
  * @brief libexpr C bindings dealing with values
  */
@@ -35,6 +38,7 @@ typedef void Value;
 typedef struct State State;
 // type defs
 /** @brief Stores an under-construction set of bindings
+ * @ingroup value_manip
  *
  * Do not reuse.
  * @see nix_make_bindings_builder, nix_bindings_builder_free, nix_make_attrs
@@ -43,18 +47,23 @@ typedef struct State State;
 typedef struct BindingsBuilder BindingsBuilder;
 
 /** @brief PrimOp function
+ * @ingroup primops
  *
  * Owned by the GC
  * @see nix_alloc_primop, nix_set_primop
  */
 typedef struct PrimOp PrimOp;
 /** @brief External Value
+ * @ingroup Externals
  *
  * Owned by the GC
- * @see nix_api_external.h
  */
 typedef struct ExternalValue ExternalValue;
 
+/** @defgroup primops
+ * @brief Create your own primops
+ * @{
+ */
 /** @brief Function pointer for primops
  * @param[in] state Evaluator state
  * @param[in] pos position of function call
@@ -79,6 +88,7 @@ typedef void (*PrimOpFun)(State *state, int pos, Value **args, Value *v);
  */
 PrimOp *nix_alloc_primop(nix_c_context *context, PrimOpFun fun, int arity,
                          const char *name, const char **args, const char *doc);
+/** @} */
 
 // Function prototypes
 
@@ -91,6 +101,10 @@ PrimOp *nix_alloc_primop(nix_c_context *context, PrimOpFun fun, int arity,
  *
  */
 Value *nix_alloc_value(nix_c_context *context, State *state);
+/** @addtogroup value_manip Manipulating values
+ * @brief Functions to inspect and change nix Value's
+ * @{
+ */
 /** @name Getters
  */
 /**@{*/
@@ -328,10 +342,12 @@ nix_err nix_bindings_builder_insert(nix_c_context *context,
  * @param[in] builder the builder to free
  */
 void nix_bindings_builder_free(BindingsBuilder *builder);
+/**@}*/
 
 // cffi end
 #ifdef __cplusplus
 }
 #endif
 
+/** @} */
 #endif // NIX_API_VALUE_H