--- a/scid/db.h	Thu Aug 04 14:59:33 2022 +0200
+++ b/scid/db.h	Thu Aug 04 16:47:10 2022 +0200
@@ -19,52 +19,175 @@
 #ifndef SCI_DB_H
 #define SCI_DB_H
 
+/**
+ * \file db.h
+ * \brief Database access.
+ *
+ * This module access the SQLite database.
+ *
+ * A global variable is used to access the database, the function \ref db_open
+ * must be called before any other functions.
+ *
+ * Many of the function that insert or update model will also update the JSON
+ * object to fill the generated row id if any.
+ *
+ * This module logs message with tag `db`.
+ */
+
 #include <stdint.h>
 
 #include <jansson.h>
 
-int
-db_open(const char *);
-
+/**
+ * Open database specified by path.
+ *
+ * \pre path != NULL
+ * \param path path to the database
+ */
 int
-db_job_add(json_t *);
+db_open(const char *path);
+
+/**
+ * Add a new job.
+ *
+ * \pre job != NULL
+ * \param job the job to add
+ * \return 0 on success or -1 on error
+ */
+int
+db_job_add(json_t *job);
 
+/**
+ * Get a list of jobs to perform for this worker.
+ *
+ * The returned list will only contain jobs to perform if their date are
+ * greater or equal to the worker creation date to avoid running jobs that are
+ * older and probably too numerous.
+ *
+ * \pre worker != NULL
+ * \param worker the worker name
+ * \return the JSON model or NULL on failure
+ */
 json_t *
-db_job_todo(const char *);
+db_job_todo(const char *worker);
 
+/**
+ * Return the whole list of jobs for the given project.
+ *
+ * \pre project != NULL
+ * \param project the project name
+ * \return the JSON model or NULL on failure
+ */
 json_t *
-db_job_list(const char *);
+db_job_list(const char *project);
 
+/**
+ * Add a new job result.
+ *
+ * \pre result != NULL
+ * \param result the job result to add
+ * \return 0 on success or -1 on error
+ */
 int
-db_jobresult_add(json_t *);
+db_jobresult_add(json_t *result);
 
+/**
+ * Get a list of job results by job id.
+ *
+ * This will contain every job done by all workers for this job id.
+ *
+ * \param job_id the job id
+ * \return the JSON model or NULL on failure
+ */
 json_t *
-db_jobresult_list_by_job(intmax_t);
+db_jobresult_list_by_job(intmax_t job_id);
 
+/**
+ * Get a list of job results for this job id but only the more recent per each
+ * worker.
+ *
+ * This function is handy if you want to retrieve all last jobs realized by all
+ * workers.
+ *
+ * \param job_id the job id
+ * \return the JSON model or NULL on failure
+ */
 json_t *
 db_jobresult_list_by_job_group(intmax_t);
 
+/**
+ * Get a list of job results realized by this worker.
+ *
+ * \pre worker != NULL
+ * \param worker the worker name
+ * \return the JSON model or NULL on failure
+ */
 json_t *
 db_jobresult_list_by_worker(const char *);
 
+/**
+ * Add or update the given project.
+ *
+ * In case of update, all fields must be present anyway.
+ *
+ * \pre project != NULL
+ * \param project the project to update
+ * \return 0 on success or -1 on error
+ */
 int
-db_project_save(json_t *);
+db_project_save(json_t *project);
 
+/**
+ * Get a list of all projects.
+ *
+ * \return the JSON model or NULL on failure
+ */
 json_t *
 db_project_list(void);
 
+/**
+ * Find a project by name.
+ *
+ * \pre name != NULL
+ * \param name the project name
+ * \return the JSON model or NULL on failure
+ */
 json_t *
-db_project_find(const char *);
+db_project_find(const char *name);
 
+/**
+ * Add or update the given worker.
+ *
+ * In case of update, all fields must be present anyway.
+ *
+ * \pre worker != NULL
+ * \param worker the worker to update
+ * \return 0 on success or -1 on error
+ */
 int
-db_worker_save(json_t *);
+db_worker_save(json_t *worker);
 
+/**
+ * Get a list of all workers.
+ *
+ * \return the JSON model or NULL on failure
+ */
 json_t *
 db_worker_list(void);
 
+/**
+ * Find a worker by name.
+ *
+ * \pre name != NULL
+ * \param name the worker name
+ * \return the JSON model or NULL on failure
+ */
 json_t *
 db_worker_find(const char *);
 
+/**
+ * Close database and associated resources.
+ */
 void
 db_finish(void);