From: ametama <ametama@wafflesoft.org>
Date: Mon, 2 Feb 2026 21:11:27 +0000 (+0100)
Subject: doc: docstrings
X-Git-Url: https://git.wafflesoft.org/?a=commitdiff_plain;ds=inline;p=ngsolve.git

doc: docstrings
---

diff --git a/src/main.c b/src/main.c
index 42ab57d..c604877 100644
--- a/src/main.c
+++ b/src/main.c
@@ -25,6 +25,15 @@ char *macros = \
     "#define Gt(a, b) Lt(b, a)\n"
     "#define Band(v, lo, hi) Lt(lo, v) + Lt(v, hi)\n";
 
+/**
+ * Read file contents into a string.
+ * !!! WARNING !!!
+ * The pointer this function returns should
+ * be freed before it leaves scope.
+ *
+ * @param f FILE* to read off of.
+ * @return string, stored on heap.
+ */
 char *readfile(FILE *f) {
     if (f == NULL) return NULL;
     int c;
@@ -37,6 +46,15 @@ char *readfile(FILE *f) {
     return str;
 }
 
+/**
+ * Read stream (fd) contents into string.
+ * !!! WARNING !!!
+ * The pointer this function returns should
+ * be freed before it leaves scope.
+ *
+ * @param fd file descriptor to read off of.
+ * @return string, stored on heap.
+ */
 char *readstream(int fd) {
     int s = 128;
     int r;
@@ -54,6 +72,14 @@ char *readstream(int fd) {
     return buf;
 }
 
+/**
+ * Read netlist from file at `task->netlist_file`, apply
+ * macros and store the netlist in `task->netlist` as a string.
+ * !!! WARNING !!!
+ * `task->netlist` should be freed before `task` leaves scope.
+ *
+ * @param task task definition.
+ */
 void load_netlist(task_def *task) {
     FILE *netlist = fopen( task->netlist_file, "r");
     char *netlist_raw = readfile(netlist);
@@ -82,6 +108,11 @@ void load_netlist(task_def *task) {
     close(out[0]);
 }
 
+/**
+ * Launch ngspice as a child process and assign pid, pipes to `chp`.
+ *
+ * @param chp child process struct to assign pid, pipes to
+ */
 void spawn_ngspice(ngspice_process *chp) {
     if (pipe(chp->input) || pipe(chp->output)) {
         printf("ngsolve: FATAL EXCEPTION\n    pipe creation unsuccessful.");
@@ -107,6 +138,13 @@ void spawn_ngspice(ngspice_process *chp) {
     chp->pid = p;
 }
 
+/**
+ * Calculate fitness of design vector `x` given the specification
+ * in the netlist source. For usage with any cgo algorithm.
+ *
+ * @param x design vector, length matching number of design variables.
+ * @return fitness.
+ */
 double fitness(double *x) {
     ngspice_process chp;
     spawn_ngspice(&chp);
@@ -130,7 +168,12 @@ double fitness(double *x) {
     return constraints + fitness;
 }
 
-void optimize(task_def *task) {
+/**
+ * Run optimization task using definition `task`.
+ *
+ * @param task definition to use for execution.
+ */
+void run_task(task_def *task) {
     double *sample_range_min = malloc(sizeof(double) * task->dvarc);
     double *sample_range_max = malloc(sizeof(double) * task->dvarc);
     for (size_t d = 0; d < task->dvarc; d++) {
@@ -173,6 +216,6 @@ int main(int argc, char *argv[]) {
     taskg.dvarc = 2;
     taskg.dvars = dvars;
     load_netlist(&taskg);
-    optimize(&taskg);
+    run_task(&taskg);
     return 0;
 }