start documentation process

21 files changed, 128 insertions, 6 deletions

diff --git a/Makefile b/Makefile
index 7b2af9a..777df9b 100644
--- a/Makefile
+++ b/Makefile
@@ -45,7 +45,8 @@ license:
 
 .PHONY: docs
 docs:
-	./scripts/warn-undocumented
+	find src include -iname '*.[ch]' |\
+		xargs ./scripts/warn-undocumented
 	doxygen docs/doxygen.conf
 
 .PHONY: check
diff --git a/include/ek/actualize.h b/include/ek/actualize.h
index f98df07..18755b1 100644
--- a/include/ek/actualize.h
+++ b/include/ek/actualize.h
@@ -4,6 +4,14 @@
 #ifndef ANALYZE_H
 #define ANALYZE_H
 
+/**
+ * @file actualize.h
+ *
+ * Actualization stuff, that is stuff needed for turning raw AST
+ * into processed AST that can be passed to a backend to generate
+ * code.
+ */
+
 #include <assert.h>
 
 #include "ast.h"
diff --git a/include/ek/ast.h b/include/ek/ast.h
index 3c55c1f..6d0f2b1 100644
--- a/include/ek/ast.h
+++ b/include/ek/ast.h
@@ -4,6 +4,12 @@
 #ifndef AST_H
 #define AST_H
 
+/**
+ * @file ast.h
+ *
+ * Abstract syntax tree handling.
+ */
+
 enum ast_binops {
 	AST_ADD,
 	AST_SUB,
diff --git a/include/ek/compiler.h b/include/ek/compiler.h
index 21ac7a2..8e3d221 100644
--- a/include/ek/compiler.h
+++ b/include/ek/compiler.h
@@ -4,6 +4,12 @@
 #ifndef EK_COMPILER_H
 #define EK_COMPILER_H
 
+/**
+ * @file compiler.h
+ *
+ * Top level compiler.
+ */
+
 #include <ek/scope.h>
 
 int compile(const char *file);
diff --git a/include/ek/debug.h b/include/ek/debug.h
index a6e2f57..7dca003 100644
--- a/include/ek/debug.h
+++ b/include/ek/debug.h
@@ -4,6 +4,12 @@
 #ifndef EK_DEBUG_H
 #define EK_DEBUG_H
 
+/**
+ * @file debug.h
+ *
+ * Debugging and general information printing helpers.
+ */
+
 #include <stdio.h>
 
 #include <ek/ast.h>
diff --git a/include/ek/imports.h b/include/ek/imports.h
index c8fdfaf..801eb06 100644
--- a/include/ek/imports.h
+++ b/include/ek/imports.h
@@ -4,6 +4,14 @@
 #ifndef EK_IMPORTS_H
 #define EK_IMPORTS_H
 
+/**
+ * @file imports.h
+ *
+ * File import handling.
+ * Currently mostly unimplemented, but intended to keep track
+ * of which files have been imported.
+ */
+
 #include <stdbool.h>
 
 void add_import_path(const char *dir);
diff --git a/include/ek/parser.h b/include/ek/parser.h
index 75322b9..f0425a4 100644
--- a/include/ek/parser.h
+++ b/include/ek/parser.h
@@ -4,6 +4,12 @@
 #ifndef PARSER_H
 #define PARSER_H
 
+/**
+ * @file parser.h
+ *
+ * Glue file to get lexer and parser to play nice.
+ */
+
 #include <stddef.h>
 #include <stdbool.h>
 #include <ek/ast.h>
diff --git a/include/ek/path.h b/include/ek/path.h
index 6e918a8..2ddfb4c 100644
--- a/include/ek/path.h
+++ b/include/ek/path.h
@@ -4,6 +4,12 @@
 #ifndef EK_PATH
 #define EK_PATH
 
+/**
+ * @file path.h
+ *
+ * Path handling helpers.
+ */
+
 char *ek_basename(const char *file);
 char *ek_dirname(const char *file);
 char *ek_cwdname();
diff --git a/include/ek/scope.h b/include/ek/scope.h
index 5962014..56e5915 100644
--- a/include/ek/scope.h
+++ b/include/ek/scope.h
@@ -4,6 +4,12 @@
 #ifndef SCOPE_H
 #define SCOPE_H
 
+/**
+ * @file scope.h
+ *
+ * Scope handling stuff.
+ */
+
 #include "ast.h"
 #include "debug.h"
 
diff --git a/include/ek/string.h b/include/ek/string.h
index 7e93eb0..5c561a7 100644
--- a/include/ek/string.h
+++ b/include/ek/string.h
@@ -4,6 +4,13 @@
 #ifndef EK_STRING_H
 #define EK_STRING_H
 
+/**
+ * @file string.h
+ *
+ * String handling helper stuff.
+ * At the moment mostly unused.
+ */
+
 #include <stddef.h>
 #include <string.h>
 #include <stdbool.h>
diff --git a/scripts/warn-undocumented b/scripts/warn-undocumented
index f1367bd..db22249 100755
--- a/scripts/warn-undocumented
+++ b/scripts/warn-undocumented
@@ -1,6 +1,7 @@
 #!/bin/sh
-# look through all files for either @file or \file, grep -c will report
-# ./example.file:0 if it is not found.
-find src -iname '*.[ch]' -exec \
-	grep -c '[@\]file' {} \+ \
-	| awk -F':' '$2 == 0 {print "Undocumented file:", $1}'
+# look through all files for either @file or \file
+for file in $@
+do
+	grep -c '[@\]file' "$file" |\
+	awk -F':' "\$1 == 0 {print \"Undocumented file: $file\"}"
+done
diff --git a/src/actualize.c b/src/actualize.c
index 4bc53fa..866f438 100644
--- a/src/actualize.c
+++ b/src/actualize.c
@@ -1,6 +1,12 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file actualize.c
+ *
+ * Implementations for stuff actualization.
+ */
+
 #include <assert.h>
 #include <string.h>
 #include <stdlib.h>
diff --git a/src/ast.c b/src/ast.c
index 57a0b3b..f632624 100644
--- a/src/ast.c
+++ b/src/ast.c
@@ -1,6 +1,12 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file ast.c
+ *
+ * Abstract syntax tree handling implementations.
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdarg.h>
diff --git a/src/compiler.c b/src/compiler.c
index 4168400..68414c7 100644
--- a/src/compiler.c
+++ b/src/compiler.c
@@ -1,6 +1,12 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file compiler.c
+ *
+ * Top level compiler implementation.
+ */
+
 #include <stdbool.h>
 #include <string.h>
 #include <unistd.h>
diff --git a/src/debug.c b/src/debug.c
index 0075dba..1be19af 100644
--- a/src/debug.c
+++ b/src/debug.c
@@ -1,6 +1,12 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file debug.c
+ *
+ * Debugging and information printing helper implementations.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <assert.h>
diff --git a/src/imports.c b/src/imports.c
index 7f1cb29..f2a240b 100644
--- a/src/imports.c
+++ b/src/imports.c
@@ -1,10 +1,17 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file imports.c
+ *
+ * File import handling implementations.
+ */
+
 #include <ek/imports.h>
 #include <ek/debug.h>
 
 void add_import_path(const char *dir)
 {
 	debug("adding import path %s...\n", dir);
+	/** @todo actually implement */
 }
diff --git a/src/main.c b/src/main.c
index 7878d46..9077061 100644
--- a/src/main.c
+++ b/src/main.c
@@ -1,6 +1,13 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file main.c
+ *
+ * Compiler main file, controls compilation and command line
+ * handling.
+ */
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <unistd.h>
diff --git a/src/parser_helper.c b/src/parser_helper.c
index ff4bc59..15dd6e8 100644
--- a/src/parser_helper.c
+++ b/src/parser_helper.c
@@ -1,6 +1,12 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file parser_helper.c
+ *
+ * Stuff to aid in parsing.
+ */
+
 #include <stdarg.h>
 
 #include <ek/parser.h>
diff --git a/src/path.c b/src/path.c
index ed032e4..2843096 100644
--- a/src/path.c
+++ b/src/path.c
@@ -1,6 +1,12 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file path.c
+ *
+ * Path handling helper implementations.
+ */
+
 #include <stddef.h>
 #include <string.h>
 #include <unistd.h>
diff --git a/src/scope.c b/src/scope.c
index 22df9f9..8e9f74e 100644
--- a/src/scope.c
+++ b/src/scope.c
@@ -1,6 +1,11 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/** @file scope.c
+ *
+ * Implementations for scope handling stuff.
+ */
+
 #include <stddef.h>
 #include <string.h>
 #include <stdio.h>
diff --git a/src/string.c b/src/string.c
index d36d6bc..3dbc3f1 100644
--- a/src/string.c
+++ b/src/string.c
@@ -1,6 +1,12 @@
 /* SPDX-License-Identifier: copyleft-next-0.3.1 */
 /* Copyright 2023 Kim Kuparinen < kimi.h.kuparinen@gmail.com > */
 
+/**
+ * @file string.c
+ *
+ * String handling implementations.
+ */
+
 #include <errno.h>
 #include <stdlib.h>