add @file info to all files

+ Next step, start documenting contents of each file.

96 files changed, 643 insertions, 15 deletions

diff --git a/Makefile b/Makefile
index 6c62903..3d790cf 100644
--- a/Makefile
+++ b/Makefile
@@ -100,8 +100,14 @@ format:
 	find arch lib common include -iname '*.[ch]' \
 		-exec clang-format -i -style=file {} \+
 
+.PHONY: docs
+docs:
+	./scripts/warn-undocumented
+	doxygen docs/doxygen.conf
+
 RM	?= rm -f
 
+.PHONY: clean
 clean:
 	$(RM) -r $(CLEANUP)
 
diff --git a/arch/riscv64/config.h b/arch/riscv64/config.h
index ee337b4..33c84a0 100644
--- a/arch/riscv64/config.h
+++ b/arch/riscv64/config.h
@@ -1,3 +1,15 @@
+#ifndef APOS_RISCV_CONFIG_H
+#define APOS_RISCV_CONFIG_H
+
+/**
+ * @file config.h
+ * riscv64 specific configuration parameters, currently mixing user-specified
+ * and immutable parameters. Included on the command line by
+ * -include.
+ *
+ * @todo Consider separating user-specified and immutable parameters.
+ */
+
 #include <apos/sizes.h>
 
 /* --- START ARCH USER CONFIG VALUES --- */
@@ -52,3 +64,4 @@
 #define PROC_STACK_TOP  (SZ_4G)
 #define PROC_STACK_BASE (SZ_4G - SZ_8M)
 #endif
+#endif /* APOS_RISCV_CONFIG_H */
diff --git a/arch/riscv64/gen/asm-offsets.c b/arch/riscv64/gen/asm-offsets.c
index 6920245..bbd1712 100644
--- a/arch/riscv64/gen/asm-offsets.c
+++ b/arch/riscv64/gen/asm-offsets.c
@@ -1,3 +1,9 @@
+/**
+ * @file asm-offsets.c
+ * riscv64 file used to generate offsets to register slots in stack. See \ref
+ * _save_context.
+ */
+
 #include <apos/utils.h>
 #include <regs.h>
 
diff --git a/arch/riscv64/include/cpu.h b/arch/riscv64/include/cpu.h
index 40a8c17..5d496ea 100644
--- a/arch/riscv64/include/cpu.h
+++ b/arch/riscv64/include/cpu.h
@@ -1 +1,8 @@
-/* empty */
+#ifndef APOS_RISCV_CPU_H
+#define APOS_RISCV_CPU_H
+/**
+ * @file cpu.h
+ * riscv64 cpu header, currently empty but kept around for forwards
+ * compatibility.
+ */
+#endif /* APOS_RISCV_CPU_H */
diff --git a/arch/riscv64/include/csr.h b/arch/riscv64/include/csr.h
index ae0763b..93bba2b 100644
--- a/arch/riscv64/include/csr.h
+++ b/arch/riscv64/include/csr.h
@@ -1,6 +1,11 @@
 #ifndef APOS_CSR_H
 #define APOS_CSR_H
 
+/**
+ * @file csr.h
+ * riscv64-specific header for CSR handling
+ */
+
 #define SATP_MODE_Sv32       0x80000000
 #define SATP_MODE_Sv39       0x8000000000000000
 #define SATP_MODE_Sv48       0x9000000000000000
diff --git a/arch/riscv64/include/lock.h b/arch/riscv64/include/lock.h
index 4f71344..15e5765 100644
--- a/arch/riscv64/include/lock.h
+++ b/arch/riscv64/include/lock.h
@@ -1 +1,15 @@
+#ifndef APOS_RISCV_LOCK_H
+#define APOS_RISCV_LOCK_H
+/**
+ * @file lock.h
+ * riscv64 implementation of arch-specific lock behaviour, currently only \ref
+ * optional_pause().
+ */
+
+/**
+ * riscv64 does not have a way to inform the cpu of a spinlock (at least at the
+ * moment, it may be added in as a hint later on)
+ */
 #define optional_pause()
+
+#endif /* APOS_RISCV_LOCK_H */
diff --git a/arch/riscv64/include/pages.h b/arch/riscv64/include/pages.h
index 20dab3d..3f4b632 100644
--- a/arch/riscv64/include/pages.h
+++ b/arch/riscv64/include/pages.h
@@ -1,14 +1,49 @@
 #ifndef APOS_RISCV_PAGES_H
 #define APOS_RISCV_PAGES_H
 
+/**
+ * @file pages.h
+ * riscv64-specific shorthands for some page sizes.
+ */
+
+/**
+ * riscv64 4KiB page, order 0.
+ */
 #define MM_KPAGE      MM_O0
+
+/**
+ * riscv64 2MiB page, order 1.
+ */
 #define MM_MPAGE      MM_O1
+
+/**
+ * riscv64 1GiB page, order 2.
+ */
 #define MM_GPAGE      MM_O2
+
+/**
+ * riscv64 512GiB page, order 3.
+ */
 #define MM_TPAGE      MM_O3
 
+/**
+ * riscv64 4KiB page size.
+ */
 #define MM_KPAGE_SIZE SZ_4K
+
+/**
+ * riscv64 2MiB page size.
+ */
 #define MM_MPAGE_SIZE SZ_2M
+
+/**
+ * riscv64 1GiB page size.
+ */
 #define MM_GPAGE_SIZE SZ_1G
+
+/**
+ * riscv64 512GiB page size.
+ */
 #define MM_TPAGE_SIZE SZ_512G
 
 #endif /* APOS_RISCV_PAGES_H */
diff --git a/arch/riscv64/include/pmem.h b/arch/riscv64/include/pmem.h
index 40a8c17..56d22ca 100644
--- a/arch/riscv64/include/pmem.h
+++ b/arch/riscv64/include/pmem.h
@@ -1 +1,8 @@
-/* empty */
+#ifndef APOS_RISCV_PMEM_H
+#define APOS_RISCV_PMEM_H
+/**
+ * @file pmem.h
+ * riscv64-specific physical memory, currently empty but kept around for
+ * forwards compatibility.
+ */
+#endif /* APOS_RISCV_PMEM_H */
diff --git a/arch/riscv64/include/regs.h b/arch/riscv64/include/regs.h
index 699af8b..c785ea6 100644
--- a/arch/riscv64/include/regs.h
+++ b/arch/riscv64/include/regs.h
@@ -1,6 +1,15 @@
 #ifndef APOS_RISCV_REGS_H
 #define APOS_RISCV_REGS_H
 
+/**
+ * @file regs.h
+ * riscv64 registers, currently only base extension integer regs. Used to \ref
+ * _save_context. Used in \ref arch/riscv64/gen/asm-offsets.c to generate a list
+ * of offsets usable from assembly.
+ *
+ * @todo Implement sacing floating point, vector, etc. registers.
+ */
+
 struct riscv_regs {
 	long ra, sp, gp, tp, t0, t1, t2, s0, s1, a0, a1, a2, a3, a4, a5, a6, a7,
 		s2, s3, s4, s5, s6, s7, s8, s9, s10, s11, t3, t4, t5, t6;
diff --git a/arch/riscv64/include/sbi.h b/arch/riscv64/include/sbi.h
index 3beedd2..44eec4f 100644
--- a/arch/riscv64/include/sbi.h
+++ b/arch/riscv64/include/sbi.h
@@ -1,6 +1,11 @@
 #ifndef APOS_RISCV_SBI_H
 #define APOS_RISCV_SBI_H
 
+/**
+ * @file sbi.h
+ * riscv64-specific OpenSBI definitions.
+ */
+
 #include <apos/types.h>
 
 struct sbiret {
diff --git a/arch/riscv64/include/tcb.h b/arch/riscv64/include/tcb.h
index d1e0717..be6d58a 100644
--- a/arch/riscv64/include/tcb.h
+++ b/arch/riscv64/include/tcb.h
@@ -1,6 +1,11 @@
 #ifndef ARCH_RISCV_TCB_H
 #define ARCH_RISCV_TCB_H
 
+/**
+ * @file tcb.h
+ * riscv64 definitions of arch-specific tcb data.
+ */
+
 struct arch_tcbd {
 	/* empty for now, but should probably be filled with stuff like register
 	 * saving of something */
diff --git a/arch/riscv64/include/types.h b/arch/riscv64/include/types.h
index 59a2762..8cb41bf 100644
--- a/arch/riscv64/include/types.h
+++ b/arch/riscv64/include/types.h
@@ -1,6 +1,12 @@
 #ifndef APOS_RISCV_TYPES_H
 #define APOS_RISCV_TYPES_H
 
+/**
+ * @file types.h
+ * riscv64 definitions of arch-specific data types, possibly made redundant by
+ * \ref include/apos/types.h but kept around just to be sure.
+ */
+
 #include <apos/types.h>
 
 typedef uintptr_t vm_t;
diff --git a/arch/riscv64/include/vmem.h b/arch/riscv64/include/vmem.h
index 7e8e915..a557513 100644
--- a/arch/riscv64/include/vmem.h
+++ b/arch/riscv64/include/vmem.h
@@ -1,6 +1,13 @@
 #ifndef APOS_RISCV_VMAP_H
 #define APOS_RISCV_VMAP_H
 
+/**
+ * @file vmem.h
+ * riscv64 definitions of arch-specific virtual memory data types and macros.
+ * Very likely VM_* should be moved to \ref include/apos/vmem.h and made
+ * architecture-nonspecific, but works for now.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 
diff --git a/arch/riscv64/init/init.c b/arch/riscv64/init/init.c
index bc68ea8..5984d3c 100644
--- a/arch/riscv64/init/init.c
+++ b/arch/riscv64/init/init.c
@@ -1,3 +1,9 @@
+/**
+ * @file init.c
+ * riscv64 'bootstrap', move actual kernel into place and jump to virtual
+ * memory.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 #include <apos/utils.h>
diff --git a/arch/riscv64/kernel/cpu.c b/arch/riscv64/kernel/cpu.c
index 3583a94..0558040 100644
--- a/arch/riscv64/kernel/cpu.c
+++ b/arch/riscv64/kernel/cpu.c
@@ -1,3 +1,8 @@
+/**
+ * @file cpu.c
+ * riscv64 implementation of cpu handling.
+ */
+
 #include <arch/cpu.h>
 
 id_t cpu_id()
diff --git a/arch/riscv64/kernel/irq.c b/arch/riscv64/kernel/irq.c
index fdcd21e..eb5dc02 100644
--- a/arch/riscv64/kernel/irq.c
+++ b/arch/riscv64/kernel/irq.c
@@ -1,3 +1,8 @@
+/**
+ * @file irq.c
+ * riscv64 implementation of irq handling.
+ */
+
 #include <apos/attrs.h>
 #include <apos/debug.h>
 #include <arch/irq.h>
diff --git a/arch/riscv64/kernel/main.c b/arch/riscv64/kernel/main.c
index 245fc9e..2cc1e12 100644
--- a/arch/riscv64/kernel/main.c
+++ b/arch/riscv64/kernel/main.c
@@ -1,3 +1,8 @@
+/**
+ * @file main.c
+ * riscv64 main
+ */
+
 #include <apos/utils.h>
 #include <arch/arch.h>
 #include <csr.h>
diff --git a/arch/riscv64/kernel/pmem.c b/arch/riscv64/kernel/pmem.c
index fc3fa40..0657244 100644
--- a/arch/riscv64/kernel/pmem.c
+++ b/arch/riscv64/kernel/pmem.c
@@ -1,3 +1,8 @@
+/**
+ * @file pmem.c
+ * riscv64 implementation of arch-specific physical memory handling
+ */
+
 #include <arch/pmem.h>
 
 stat_t stat_pmem_conf(void *fdt, size_t *max_order, size_t *base_bits,
diff --git a/arch/riscv64/kernel/power.c b/arch/riscv64/kernel/power.c
index a4d6568..061c286 100644
--- a/arch/riscv64/kernel/power.c
+++ b/arch/riscv64/kernel/power.c
@@ -1,3 +1,8 @@
+/**
+ * @file power.c
+ * riscv64 implementation of arch-specific power handling.
+ */
+
 #include <apos/power.h>
 #include <sbi.h>
 
diff --git a/arch/riscv64/kernel/proc.c b/arch/riscv64/kernel/proc.c
index 8653254..51a4ab3 100644
--- a/arch/riscv64/kernel/proc.c
+++ b/arch/riscv64/kernel/proc.c
@@ -1,3 +1,8 @@
+/**
+ * @file proc.c
+ * riscv64 implementation of arch-specific process handling.
+ */
+
 #include <apos/tcb.h>
 #include <apos/elf.h>
 #include <regs.h>
diff --git a/arch/riscv64/kernel/sbi.c b/arch/riscv64/kernel/sbi.c
index 93f5785..feadd8d 100644
--- a/arch/riscv64/kernel/sbi.c
+++ b/arch/riscv64/kernel/sbi.c
@@ -1,3 +1,8 @@
+/**
+ * @file sbi.c
+ * riscv64 specific OpenSBI handling.
+ */
+
 #include <sbi.h>
 
 struct sbiret sbi_ecall(int ext, int fid, unsigned long arg0,
diff --git a/arch/riscv64/kernel/timer.c b/arch/riscv64/kernel/timer.c
index 1f79c5b..98f8e16 100644
--- a/arch/riscv64/kernel/timer.c
+++ b/arch/riscv64/kernel/timer.c
@@ -1,3 +1,8 @@
+/**
+ * @file timer.c
+ * riscv64 implementation of arch-specific timers.
+ */
+
 #include <arch/timer.h>
 #include <libfdt.h>
 #include <csr.h>
diff --git a/arch/riscv64/kernel/vmem.c b/arch/riscv64/kernel/vmem.c
index 29bc084..56b04f3 100644
--- a/arch/riscv64/kernel/vmem.c
+++ b/arch/riscv64/kernel/vmem.c
@@ -1,3 +1,8 @@
+/**
+ * @file vmem.c
+ * riscv64 implementation of arch-specific virtual memory handling.
+ */
+
 #include <apos/string.h>
 #include <apos/pmem.h>
 #include <apos/vmem.h>
diff --git a/common/bits.c b/common/bits.c
index 698c082..dde39f7 100644
--- a/common/bits.c
+++ b/common/bits.c
@@ -1,3 +1,8 @@
+/**
+ * @file bits.c
+ * Bit manipulation helper implementations, currently just byte swaps.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 #include <apos/bits.h>
diff --git a/common/debug.c b/common/debug.c
index a008a52..15f71dc 100644
--- a/common/debug.c
+++ b/common/debug.c
@@ -1,3 +1,9 @@
+/**
+ * @file debug.c
+ * Handle printing to serial. Note that the serial drivers are only included
+ * when running a debug build to save space in release mode.
+ */
+
 #include <apos/types.h>
 #include <apos/debug.h>
 #include <apos/bits.h>
diff --git a/common/dmem.c b/common/dmem.c
index a116547..1d5608c 100644
--- a/common/dmem.c
+++ b/common/dmem.c
@@ -1,3 +1,10 @@
+/**
+ * @file dmem.c
+ * Handle device memory, i.e. anything outside the physical RAM.
+ *
+ * \todo Handle NUMA.
+ */
+
 #include <apos/dmem.h>
 
 static struct mem_region_root pre_ram = { 0 };
diff --git a/common/elf.c b/common/elf.c
index 9af4f08..e60b21f 100644
--- a/common/elf.c
+++ b/common/elf.c
@@ -1,3 +1,8 @@
+/**
+ * @file elf.c
+ * Handle elf executables, set up requested memory mappings etc.
+ */
+
 #include <apos/elf.h>
 #include <apos/vmem.h>
 #include <apos/bits.h>
diff --git a/common/fdt.c b/common/fdt.c
index 56b9d04..a6368dd 100644
--- a/common/fdt.c
+++ b/common/fdt.c
@@ -1,3 +1,8 @@
+/**
+ * @file fdt.c
+ * Helper functions for handling the global FDT.
+ */
+
 #include <libfdt.h>
 
 struct cell_info get_cellinfo(const void *fdt, const int offset)
diff --git a/common/initrd.c b/common/initrd.c
index 28ddaec..e3e6d94 100644
--- a/common/initrd.c
+++ b/common/initrd.c
@@ -1,3 +1,8 @@
+/**
+ * @file initrd.c
+ * Handle initrd, implement cpio with newc format.
+ */
+
 #include <apos/initrd.h>
 #include <apos/vmem.h>
 #include <apos/string.h>
diff --git a/common/main.c b/common/main.c
index b2928be..9585f3d 100644
--- a/common/main.c
+++ b/common/main.c
@@ -1,3 +1,8 @@
+/**
+ * @file main.c
+ * Entry point for actual kernel setup.
+ */
+
 #include <apos/mem_nodes.h>
 #include <apos/timer.h>
 #include <apos/attrs.h>
diff --git a/common/mem.c b/common/mem.c
index a824c26..51a51af 100644
--- a/common/mem.c
+++ b/common/mem.c
@@ -1,3 +1,8 @@
+/**
+ * @file mem.c
+ * Generic memory handling, used both by physical and virtual memory.
+ */
+
 #include <apos/types.h>
 #include <apos/mem.h>
 #include <apos/vmem.h>
diff --git a/common/mem_nodes.c b/common/mem_nodes.c
index 392fa3e..d4f7d2e 100644
--- a/common/mem_nodes.c
+++ b/common/mem_nodes.c
@@ -1,3 +1,12 @@
+/**
+ * @file mem_nodes.c
+ * Memory node wrapper around the node subsystem, used by \ref
+ * common/mem_regions.c.
+ *
+ * Each region of memory is allocated through a \ref mem_region node, which is
+ * allocated through the node subsystem.
+ */
+
 #include <apos/vmem.h>
 #include <apos/pmem.h>
 #include <apos/mem.h>
diff --git a/common/mem_regions.c b/common/mem_regions.c
index e6c4644..e1eff0d 100644
--- a/common/mem_regions.c
+++ b/common/mem_regions.c
@@ -1,3 +1,9 @@
+/**
+ * @file mem_regions.c
+ * Memory region handling, used by both device memory and user virtual memory
+ * subsystems.
+ */
+
 #include <apos/mem_regions.h>
 #include <apos/mem_nodes.h>
 #include <apos/pmem.h>
diff --git a/common/nodes.c b/common/nodes.c
index 0c6f7ce..30d3cfb 100644
--- a/common/nodes.c
+++ b/common/nodes.c
@@ -1,3 +1,28 @@
+/**
+ * @file nodes.c
+ * The node subsystem. Each client has to initialize their own node system,
+ * after which they can request nodes of a size specified at init.
+ *
+ * Node allocation is implemented through a similar system used by jemalloc
+ * (https://github.com/jemalloc/jemalloc), but instead of having a number of
+ * different sized buckets there is only the one size specified by the user.
+ * This cuts down on complexity and improves performance, at a somewhat major
+ * flexibility cost. Still, this kernel generally only allocates nodes of the
+ * same size again and again, and this approach seems sensible.
+ *
+ *
+ * Quick overview of the allocator, all nodes live in memory pages. Each memory
+ * page has a small header at the front, with some metadata about number of free
+ * and used node slots. When a memory page is filled, a new one is allocated by
+ * the physical memory subsystem and the pages are linked together in a common
+ * list. At the same time, a second linked list is maintained which maintains
+ * which pages have empty slots. When a node is freed, the page it belonged to
+ * is added to the free list (if it didn't already exist there) and when a new
+ * node is requested, the free list is looked through first.
+ *
+ * \todo More in-depth documentation about the node algorithm.
+ */
+
 #include <apos/mem.h>
 #include <apos/pmem.h>
 #include <apos/bits.h>
diff --git a/common/pmem.c b/common/pmem.c
index e3e5e5c..5af17ac 100644
--- a/common/pmem.c
+++ b/common/pmem.c
@@ -1,3 +1,25 @@
+/**
+ * @file pmem.c
+ * Physical memory subsystem. Allocates physical memory pages, with support for
+ * different ordered pages, depending on the underlying architecture.
+ *
+ * Quick overview of the physical memory subsystem: Somewhere in RAM there
+ * exists a number of buckets, each with an n-tree representing different order
+ * pages and their status (used/free). When a lower-order memory page (i.e.
+ * smaller) is allocated, it blocks allocation of higher-order pages (i.e.
+ * larger) whose addresses would overlap. This is avoided by marking all
+ * higher-order pages as used in their respective buckets.
+ *
+ * This approach is reasonably efficient at handling the different possible page
+ * sizes, but requires that the caller maintains some data about page sizes, as
+ * the algorithm doesn't keep any of that information. Allocating a region of a
+ * certain page order and freeing it as another could easily be a
+ * source of difficult to track bugs.
+ *
+ * \todo More in depth documentation about the physical memory algorithms,
+ * unfortunately it is quite difficult to follow.
+ */
+
 #include <apos/mem_nodes.h>
 #include <apos/pmem.h>
 #include <apos/dmem.h>
diff --git a/common/proc.c b/common/proc.c
index f4c0899..e88d37d 100644
--- a/common/proc.c
+++ b/common/proc.c
@@ -1,3 +1,8 @@
+/**
+ * @file proc.c
+ * Process handling, might be merged into \ref common/tcb.c.
+ */
+
 #include <apos/elf.h>
 #include <apos/proc.h>
 #include <apos/conf.h>
diff --git a/common/sp_tree.c b/common/sp_tree.c
index 5097757..9003f40 100644
--- a/common/sp_tree.c
+++ b/common/sp_tree.c
@@ -1,3 +1,13 @@
+/**
+ * @file sp_tree.c
+ * Implementation of my sp_trees. An sp_tree is a mix of rb-trees and avl-trees,
+ * with slightly faster insertion but worse tree depth on average.
+ *
+ * See https://github.com/Kimplul/sptree
+ *
+ * \todo Document sp_tree algorithm better.
+ */
+
 #include <apos/sp_tree.h>
 
 static void __sp_turn_left(struct sp_node *n)
diff --git a/common/string.c b/common/string.c
index 15416af..6a56698 100644
--- a/common/string.c
+++ b/common/string.c
@@ -1,3 +1,8 @@
+/**
+ * @file string.c
+ * Implementations of some string.h stdlib functions.
+ */
+
 #include <apos/string.h>
 #include <apos/types.h>
 #include <apos/attrs.h>
diff --git a/common/tcb.c b/common/tcb.c
index 1e8c648..6904208 100644
--- a/common/tcb.c
+++ b/common/tcb.c
@@ -1,3 +1,8 @@
+/**
+ * @file tcb.c
+ * Thread control block handling implementation.
+ */
+
 #include <apos/tcb.h>
 #include <arch/cpu.h>
 #include <apos/mem.h>
diff --git a/common/timer.c b/common/timer.c
index 0442c44..0a11dc8 100644
--- a/common/timer.c
+++ b/common/timer.c
@@ -1,3 +1,17 @@
+/**
+ * @file timer.c
+ * Timer handling implementation. Currently we only expect an architecture to
+ * support a single timer per core.
+ *
+ * By keeping all timers in a binary search
+ * tree ordered by time, we can just set the single timer to interrupt us when
+ * the next timer is due and with thread info call the thread that set the
+ * timer. From what I can tell, this is largely what Linux does.
+ *
+ * \todo Figure out if there are any advantages to having multiple concurrent
+ * timers.
+ */
+
 #include <apos/sp_tree.h>
 #include <apos/string.h>
 #include <apos/nodes.h>
diff --git a/common/uapi/conf.c b/common/uapi/conf.c
index 25677ef..a30333b 100644
--- a/common/uapi/conf.c
+++ b/common/uapi/conf.c
@@ -1,3 +1,10 @@
+/**
+ * @file conf.c
+ * Runtime configuration sycall implementations.
+ *
+ * At the moment there are not runtime configuration parameters.
+ */
+
 #include <apos/power.h>
 #include <apos/sizes.h>
 #include <apos/uapi.h>
diff --git a/common/uapi/dispatch.c b/common/uapi/dispatch.c
index 5e2e788..1e72e77 100644
--- a/common/uapi/dispatch.c
+++ b/common/uapi/dispatch.c
@@ -1,3 +1,8 @@
+/**
+ * @file dispatch.c
+ * Syscall dispatch.
+ */
+
 #include <apos/uapi.h>
 
 static const sys_t syscall_table[] = {
diff --git a/common/uapi/ipc.c b/common/uapi/ipc.c
index 0d2d287..d3cbcd7 100644
--- a/common/uapi/ipc.c
+++ b/common/uapi/ipc.c
@@ -1,3 +1,8 @@
+/**
+ * @file ipc.c
+ * Interprocess communication syscall implementations.
+ */
+
 #include <apos/uapi.h>
 #include <apos/tcb.h>
 
diff --git a/common/uapi/mem.c b/common/uapi/mem.c
index 7526152..83d7289 100644
--- a/common/uapi/mem.c
+++ b/common/uapi/mem.c
@@ -1,3 +1,8 @@
+/**
+ * @file mem.c
+ * Memory handling syscall implementations.
+ */
+
 #include <apos/uapi.h>
 #include <apos/utils.h>
 #include <apos/vmem.h>
diff --git a/common/uapi/proc.c b/common/uapi/proc.c
index 3ce3bcb..43e825d 100644
--- a/common/uapi/proc.c
+++ b/common/uapi/proc.c
@@ -1,3 +1,8 @@
+/**
+ * @file proc.c
+ * Process/thread handling syscall implementations.
+ */
+
 #include <apos/uapi.h>
 
 SYSCALL_DEFINE0(create)()
diff --git a/common/uapi/timers.c b/common/uapi/timers.c
index 97a1d30..ca2443b 100644
--- a/common/uapi/timers.c
+++ b/common/uapi/timers.c
@@ -1,3 +1,8 @@
+/**
+ * @file timers.c
+ * Timer syscall implementations.
+ */
+
 #include <apos/timer.h>
 #include <apos/uapi.h>
 
diff --git a/common/vmem.c b/common/vmem.c
index 7ea83b1..ae40748 100644
--- a/common/vmem.c
+++ b/common/vmem.c
@@ -1,3 +1,8 @@
+/**
+ * @file vmem.c
+ * Virtual memory handling, mainly userspace virtual memory.
+ */
+
 #include <apos/mem_regions.h>
 #include <apos/assert.h>
 #include <apos/debug.h>
diff --git a/docs/doxygen.conf b/docs/doxygen.conf
index 19c1568..a073704 100644
--- a/docs/doxygen.conf
+++ b/docs/doxygen.conf
@@ -640,7 +640,7 @@ INLINE_INFO            = YES
 # name. If set to NO, the members will appear in declaration order.
 # The default value is: YES.
 
-SORT_MEMBER_DOCS       = YES
+SORT_MEMBER_DOCS       = NO
 
 # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
 # descriptions of file, namespace and class members alphabetically by member
@@ -794,7 +794,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
@@ -1196,7 +1196,7 @@ CLANG_DATABASE_PATH    =
 # classes, structs, unions or interfaces.
 # The default value is: YES.
 
-ALPHABETICAL_INDEX     = YES
+ALPHABETICAL_INDEX     = NO
 
 # In case all classes in a project start with a common prefix, all classes will
 # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
diff --git a/include/apos/assert.h b/include/apos/assert.h
index f3d9a4d..eed521c 100644
--- a/include/apos/assert.h
+++ b/include/apos/assert.h
@@ -1,6 +1,20 @@
 #ifndef APOS_ASSERT_H
 #define APOS_ASSERT_H
 
+/**
+ * @file assert.h
+ * Assertions. Note that contrary to how assertios usually function, apos has
+ * three different levels of assertions: Catastrophic, hard and soft.
+ *
+ * Soft assertions merely warn about something that might cause issues, but let
+ * the execution continue normally.
+ *
+ * Hard assertions warn about the assertion not holding and returns from the
+ * function.
+ *
+ * Catastrophic assertions warn about the assertion and crash the kernel.
+ */
+
 #include <apos/debug.h>
 #include <apos/utils.h>
 
diff --git a/include/apos/atomic.h b/include/apos/atomic.h
index e6dafc8..4026b1f 100644
--- a/include/apos/atomic.h
+++ b/include/apos/atomic.h
@@ -1,6 +1,12 @@
 #ifndef ATOMIC_H
 #define ATOMIC_H
 
+/**
+ * @file atomic.h
+ * Atomics, closely modeled after C17 stdatomic.h. Largely dependent on the
+ * compiler at the moment.
+ */
+
 #include <apos/utils.h> /* GLUE */
 
 typedef enum {
diff --git a/include/apos/attrs.h b/include/apos/attrs.h
index 094ae54..dd28b65 100644
--- a/include/apos/attrs.h
+++ b/include/apos/attrs.h
@@ -1,4 +1,10 @@
 #ifndef APOS_COMPILER_ATTRIBUTES_H
+#define APOS_COMPILER_ATTRIBUTES_H
+
+/**
+ * @file attrs.h
+ * Attribute shorthands.
+ */
 
 #define __section(section) __attribute__((__section__(section)))
 #define __fmt(x, y)        __attribute__((format(__printf__, x, y)))
diff --git a/include/apos/bits.h b/include/apos/bits.h
index ca25007..66a495c 100644
--- a/include/apos/bits.h
+++ b/include/apos/bits.h
@@ -1,6 +1,11 @@
 #ifndef APOS_BITS_H
 #define APOS_BITS_H
 
+/**
+ * @file bits.h
+ * Bit manipulations.
+ */
+
 #include <apos/types.h>
 #include <apos/builtin.h>
 
diff --git a/include/apos/builtin.h b/include/apos/builtin.h
index 52a3fa2..b6ce0e0 100644
--- a/include/apos/builtin.h
+++ b/include/apos/builtin.h
@@ -1,6 +1,15 @@
 #ifndef APOS_BUILTIN_H
 #define APOS_BUILTIN_H
 
+/**
+ * @file builtin.h
+ * Defines __has_builtin, if the compiler doesn't support it.
+ *
+ * Technically we only support clang and gcc at the moment, and they both
+ * support __has_builtin, but if some interesting compiler comes along then
+ * we'll be golden.
+ */
+
 #ifndef __has_builtin
 #define __has_builtin(x) (0)
 #endif
diff --git a/include/apos/conf.h b/include/apos/conf.h
index 844ce37..2b861dc 100644
--- a/include/apos/conf.h
+++ b/include/apos/conf.h
@@ -1,6 +1,12 @@
 #ifndef APOS_CONF_H
 #define APOS_CONF_H
 
+/**
+ * @file conf.h
+ * Global configuration file, gives extern access to runtime configuration
+ * parameters when they're implemented.
+ */
+
 #include <apos/types.h>
 
 extern size_t __proc_stack_size;
diff --git a/include/apos/debug.h b/include/apos/debug.h
index 8df7342..6d49f12 100644
--- a/include/apos/debug.h
+++ b/include/apos/debug.h
@@ -1,6 +1,11 @@
 #ifndef APOS_DEBUG_H
 #define APOS_DEBUG_H
 
+/**
+ * @file debug.h
+ * Debug printing.
+ */
+
 #include <apos/attrs.h>
 #include <apos/pmem.h>
 #include <arch/vmem.h>
diff --git a/include/apos/dmem.h b/include/apos/dmem.h
index 59083cb..38476ec 100644
--- a/include/apos/dmem.h
+++ b/include/apos/dmem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_DEV_H
 #define APOS_DEV_H
 
+/**
+ * @file dmem.h
+ * Device memory handling, i.e. anything outside of RAM.
+ */
+
 #include <apos/types.h>
 #include <apos/vmem.h>
 
diff --git a/include/apos/elf.h b/include/apos/elf.h
index 7d0004a..cea504e 100644
--- a/include/apos/elf.h
+++ b/include/apos/elf.h
@@ -1,6 +1,13 @@
 #ifndef APOS_ELF_H
 #define APOS_ELF_H
 
+/**
+ * @file elf.h
+ * ELF file handling.
+ *
+ * \todo Other file formats?
+ */
+
 #include <apos/attrs.h>
 #include <apos/types.h>
 #include <apos/vmem.h>
diff --git a/include/apos/initrd.h b/include/apos/initrd.h
index 17ed94c..5644106 100644
--- a/include/apos/initrd.h
+++ b/include/apos/initrd.h
@@ -1,6 +1,11 @@
 #ifndef APOS_INITRD_H
 #define APOS_INITRD_H
 
+/**
+ * @file initrd.h
+ * Initrd handling.
+ */
+
 #include <apos/types.h>
 #include <apos/pmem.h>
 #include <apos/vmem.h>
diff --git a/include/apos/lock.h b/include/apos/lock.h
index 178140b..2fac160 100644
--- a/include/apos/lock.h
+++ b/include/apos/lock.h
@@ -1,5 +1,11 @@
-#ifndef LOCK_H
-#define LOCK_H
+#ifndef APOS_LOCK_H
+#define APOS_LOCK_H
+
+/**
+ * @file lock.h
+ * Atomic locks, currently only \ref spin_lock and \ref spin_unlock. Mutex is
+ * probably overkill for this project.
+ */
 
 #include <apos/atomic.h>
 #include <apos/irq.h>
@@ -23,4 +29,4 @@ static inline void spin_unlock(spinlock_t *lck)
 	enable_irq();
 }
 
-#endif /* LOCK_H */
+#endif /* APOS_LOCK_H */
diff --git a/include/apos/mem.h b/include/apos/mem.h
index f3eded7..bbe7532 100644
--- a/include/apos/mem.h
+++ b/include/apos/mem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_MEM_H
 #define APOS_MEM_H
 
+/**
+ * @file mem.h
+ * Generic memory, common to both physical and virtual memory.
+ */
+
 #include <apos/utils.h>
 #include <apos/types.h>
 
diff --git a/include/apos/mem_nodes.h b/include/apos/mem_nodes.h
index 50f280d..5a67f08 100644
--- a/include/apos/mem_nodes.h
+++ b/include/apos/mem_nodes.h
@@ -1,5 +1,10 @@
-#ifndef MM_NODES_H
-#define MM_NODES_H
+#ifndef APOS_MM_NODES_H
+#define APOS_MM_NODES_H
+
+/**
+ * @file mem_nodes.
+ * Memory node subsystem. Used by the memory region subsystem.
+ */
 
 #include <apos/vmem.h>
 #include <apos/nodes.h>
@@ -10,4 +15,4 @@ void destroy_mem_blocks();
 struct mem_region *get_mem_node();
 void free_mem_node(struct mem_region *m);
 
-#endif /* MM_NODES_H */
+#endif /* APOS_MM_NODES_H */
diff --git a/include/apos/mem_regions.h b/include/apos/mem_regions.h
index 2d777a9..8e9125f 100644
--- a/include/apos/mem_regions.h
+++ b/include/apos/mem_regions.h
@@ -1,6 +1,12 @@
 #ifndef APOS_MEM_REGIONS_H
 #define APOS_MEM_REGIONS_H
 
+/**
+ * @file mem_regions.h
+ * Memory region subsytem. Mainly used by the virtual memory subsytems, i.e. device and
+ * user memory.
+ */
+
 #include <apos/mem.h>
 #include <apos/types.h>
 #include <apos/sp_tree.h>
diff --git a/include/apos/nodes.h b/include/apos/nodes.h
index 9cf6728..3fefc4c 100644
--- a/include/apos/nodes.h
+++ b/include/apos/nodes.h
@@ -1,6 +1,12 @@
 #ifndef APOS_NODES_H
 #define APOS_NODES_H
 
+/**
+ * @file nodes.h
+ * Node subsystem. Used by a number of subsystems for allocating specific sizes
+ * of memory nodes smaller than memory pages.
+ */
+
 #include <apos/types.h>
 
 enum node_status { FREE = 0, USED = 1 };
diff --git a/include/apos/pmem.h b/include/apos/pmem.h
index 2ff817d..0b11555 100644
--- a/include/apos/pmem.h
+++ b/include/apos/pmem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_PMEM_H
 #define APOS_PMEM_H
 
+/**
+ * @file pmem.h
+ * Physical memory subsystem. Used to allocate and free physical memory pages.
+ */
+
 #include <apos/mem.h>
 #include <apos/types.h>
 #include <arch/pmem.h>
diff --git a/include/apos/power.h b/include/apos/power.h
index 31f199d..640f056 100644
--- a/include/apos/power.h
+++ b/include/apos/power.h
@@ -1,6 +1,12 @@
 #ifndef APOS_POWER_H
 #define APOS_POWER_H
 
+/**
+ * @file power.h
+ * Power subsystem. Will hopefully eventually be used to restart and shutdown
+ * host machines.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 
diff --git a/include/apos/proc.h b/include/apos/proc.h
index 238e0f6..6b4044d 100644
--- a/include/apos/proc.h
+++ b/include/apos/proc.h
@@ -1,6 +1,12 @@
 #ifndef APOS_PROC_H
 #define APOS_PROC_H
 
+/**
+ * @file proc.h
+ * Process handling subsystem, should likely be merged into \ref
+ * include/apos/tcb.h.
+ */
+
 #include <apos/tcb.h>
 #include <apos/vmem.h>
 
diff --git a/include/apos/sizes.h b/include/apos/sizes.h
index 1a34d48..2ac48c7 100644
--- a/include/apos/sizes.h
+++ b/include/apos/sizes.h
@@ -1,6 +1,11 @@
 #ifndef APOS_SIZES_H
 #define APOS_SIZES_H
 
+/**
+ * @file sizes.h
+ * Shorthands for some power-of-two sizes.
+ */
+
 #if defined(__ASSEMBLER__)
 
 #define SZ_1    0x000000000001
diff --git a/include/apos/sp_tree.h b/include/apos/sp_tree.h
index 65e4e89..1df781b 100644
--- a/include/apos/sp_tree.h
+++ b/include/apos/sp_tree.h
@@ -1,6 +1,11 @@
 #ifndef SP_TREE_H
 #define SP_TREE_H
 
+/**
+ * @file sp_tree.h
+ * sp_trees, a type of binary search trees.
+ */
+
 #include <apos/types.h>
 
 #define sp_root(r)       ((r)->sp_r)
diff --git a/include/apos/string.h b/include/apos/string.h
index 8a3c737..e220800 100644
--- a/include/apos/string.h
+++ b/include/apos/string.h
@@ -1,6 +1,11 @@
 #ifndef APOS_STRING_H
 #define APOS_STRING_H
 
+/**
+ * @file string.h
+ * String handling, similar to cstdlib's string.h.
+ */
+
 #include <apos/types.h>
 #include <apos/builtin.h>
 
diff --git a/include/apos/syscalls.h b/include/apos/syscalls.h
index e7b1cd5..19e27ea 100644
--- a/include/apos/syscalls.h
+++ b/include/apos/syscalls.h
@@ -1,6 +1,11 @@
 #ifndef APOS_SYSCALLS_H
 #define APOS_SYSCALLS_H
 
+/**
+ * @file syscalls.h
+ * Table of system calls.
+ */
+
 /* enum for now, possibly macros in the future once I get an approximate idea of
  * which syscalls are necessary etc. */
 enum {
diff --git a/include/apos/tcb.h b/include/apos/tcb.h
index 439a3c9..89b594d 100644
--- a/include/apos/tcb.h
+++ b/include/apos/tcb.h
@@ -1,6 +1,11 @@
 #ifndef APOS_TCB_H
 #define APOS_TCB_H
 
+/**
+ * @file tcb.h
+ * Process/thread handling.
+ */
+
 #include <apos/mem_regions.h>
 #include <apos/types.h>
 #include <tcb.h> /* arch-specific data */
diff --git a/include/apos/types.h b/include/apos/types.h
index 2f45857..45526d7 100644
--- a/include/apos/types.h
+++ b/include/apos/types.h
@@ -1,6 +1,11 @@
 #ifndef APOS_TYPES_H
 #define APOS_TYPES_H
 
+/**
+ * @file types.h
+ * Shorthands for types, similar to stdint.h.
+ */
+
 typedef _Bool bool;
 #define true 1
 #define false 0
diff --git a/include/apos/uapi.h b/include/apos/uapi.h
index b3d345f..d33a855 100644
--- a/include/apos/uapi.h
+++ b/include/apos/uapi.h
@@ -1,6 +1,11 @@
 #ifndef APOS_UAPI_H
 #define APOS_UAPI_H
 
+/**
+ * @file uapi.h
+ * Userspace api, syscall declarations.
+ */
+
 #include <apos/syscalls.h>
 #include <apos/vmem.h>
 
diff --git a/include/apos/unaligned.h b/include/apos/unaligned.h
index 1dbd253..94439ca 100644
--- a/include/apos/unaligned.h
+++ b/include/apos/unaligned.h
@@ -1,6 +1,11 @@
 #ifndef APOS_UNALIGNED_H
 #define APOS_UNALIGNED_H
 
+/**
+ * @file unaligned.h
+ * Helpers for unaligned memory accesses. Largely lifted from Linux.
+ */
+
 #include <apos/types.h>
 #include <apos/attrs.h>
 
diff --git a/include/apos/utils.h b/include/apos/utils.h
index e09a35f..25f10b0 100644
--- a/include/apos/utils.h
+++ b/include/apos/utils.h
@@ -1,6 +1,11 @@
 #ifndef APOS_UTILS_H
 #define APOS_UTILS_H
 
+/**
+ * @file utils.
+ * Misc utils and helpers.
+ */
+
 #define ABS(a)        (a < 0 ? -a : a)
 
 #define MAX(a, b)     ((a) >= (b) ? (a) : (b))
diff --git a/include/apos/vmem.h b/include/apos/vmem.h
index d55e249..663b2ab 100644
--- a/include/apos/vmem.h
+++ b/include/apos/vmem.h
@@ -1,6 +1,11 @@
 #ifndef APOS_VMEM_H
 #define APOS_VMEM_H
 
+/**
+ * @file vmem.h
+ * Virtual memory handling.
+ */
+
 #include <apos/tcb.h>
 #include <apos/mem.h>
 #include <apos/pmem.h>
diff --git a/include/arch/arch.h b/include/arch/arch.h
index f684cf0..801e363 100644
--- a/include/arch/arch.h
+++ b/include/arch/arch.h
@@ -1,6 +1,12 @@
 #ifndef APOS_ARCH_H
 #define APOS_ARCH_H
 
+/**
+ * @file arch.h
+ * Arch-specific generic stuff, generally implemented in
+ * arch/whatever/kernel/main.c
+ */
+
 #include <apos/types.h>
 
 stat_t setup_arch(void *fdt);
diff --git a/include/arch/cpu.h b/include/arch/cpu.h
index c53a4d6..cf7abde 100644
--- a/include/arch/cpu.h
+++ b/include/arch/cpu.h
@@ -1,6 +1,12 @@
 #ifndef APOS_CPU_H
 #define APOS_CPU_H
 
+/**
+ * @file cpu.h
+ * Arch-specific cpu handling, generally implemented in
+ * arch/whatever/kernel/cpu.c
+ */
+
 #include <apos/types.h>
 #include <cpu.h>
 
diff --git a/include/arch/irq.h b/include/arch/irq.h
index 3ce6556..15ad893 100644
--- a/include/arch/irq.h
+++ b/include/arch/irq.h
@@ -1,6 +1,12 @@
 #ifndef APOS_IRQ_H
 #define APOS_IRQ_H
 
+/**
+ * @file irq.h
+ * Arch-specific interrupt handling, generally implemented in
+ * arch/whatever/kernel/irq.c
+ */
+
 void init_irq(void *fdt);
 void handle_irq();
 void enable_irq();
diff --git a/include/arch/pmem.h b/include/arch/pmem.h
index 08a38ed..e492426 100644
--- a/include/arch/pmem.h
+++ b/include/arch/pmem.h
@@ -1,6 +1,12 @@
 #ifndef APOS_ARCH_PMEM_H
 #define APOS_ARCH_PMEM_H
 
+/**
+ * @file pmem.h
+ * Arch-specific physical memory handling, generally implemented in
+ * arch/whatever/kernel/pmem.c
+ */
+
 #include <apos/mem.h> /* NUM_ORDERS */
 #include <apos/types.h>
 #include <pmem.h>
diff --git a/include/arch/timer.h b/include/arch/timer.h
index 6d63565..b4b2197 100644
--- a/include/arch/timer.h
+++ b/include/arch/timer.h
@@ -1,6 +1,12 @@
 #ifndef APOS_ARCH_TIMER_H
 #define APOS_ARCH_TIMER_H
 
+/**
+ * @file timer.h
+ * Arch-specific timer handling, generally implemented in
+ * arch/whatever/timer.c
+ */
+
 #include <apos/timer.h>
 
 /* return hardware timer frequency */
diff --git a/include/arch/vmem.h b/include/arch/vmem.h
index 03bffb3..e123b47 100644
--- a/include/arch/vmem.h
+++ b/include/arch/vmem.h
@@ -1,6 +1,12 @@
 #ifndef APOS_ARCH_PAGES_H
 #define APOS_ARCH_PAGES_H
 
+/**
+ * @file vmem.h
+ * Arch-specific virtual memory handling, generally implemented in
+ * arch/whatever/kernel/vmem.c
+ */
+
 #include <vmem.h>
 
 stat_t map_vpage(struct vmem *branch, pm_t paddr, vm_t vaddr, vmflags_t flags,
diff --git a/include/fdt.h b/include/fdt.h
index f0b85e8..0bdcffa 100644
--- a/include/fdt.h
+++ b/include/fdt.h
@@ -1,4 +1,10 @@
 #ifndef APOS_FDT_H
 #define APOS_FDT_H
+
+/**
+ * @file fdt.h
+ * Wrapper around libfdt/fdt.h, mainly just for convenience.
+ */
+
 #include "../dtc/libfdt/fdt.h"
 #endif
diff --git a/include/libfdt.h b/include/libfdt.h
index 63e96fd..33ce0fb 100644
--- a/include/libfdt.h
+++ b/include/libfdt.h
@@ -1,5 +1,11 @@
 #ifndef APOS_LIBFDT_H
 #define APOS_LIBFDT_H
+
+/**
+ * @file libfdt.h
+ * Main include file in apos for functions in libfdt.
+ */
+
 #include "../dtc/libfdt/libfdt.h"
 #include <apos/unaligned.h>
 #include <apos/types.h>
diff --git a/include/libfdt_env.h b/include/libfdt_env.h
index 0e8909c..7d00910 100644
--- a/include/libfdt_env.h
+++ b/include/libfdt_env.h
@@ -2,6 +2,11 @@
 /* take over libfdt */
 #define LIBFDT_ENV_H
 
+/**
+ * @file libfdt_env.h
+ * Set up apos environment for libfdt.
+ */
+
 #include <apos/types.h>
 #include <apos/string.h>
 #include <apos/bits.h>
diff --git a/lib/fdt.c b/lib/fdt.c
index 2d910c0..800d16f 100644
--- a/lib/fdt.c
+++ b/lib/fdt.c
@@ -1,2 +1,7 @@
+/**
+ * @file fdt.c
+ * Wrapper to libfdt/fdt.c, sets up the environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt.c"
diff --git a/lib/fdt_addresses.c b/lib/fdt_addresses.c
index f7ac8ae..942d3a8 100644
--- a/lib/fdt_addresses.c
+++ b/lib/fdt_addresses.c
@@ -1,2 +1,7 @@
+/**
+ * @file
+ * Wrapper to libfdt fdt_addresses.c, sets up the environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt_addresses.c"
diff --git a/lib/fdt_dbg.c b/lib/fdt_dbg.c
index bf8e2d9..377ecdd 100644
--- a/lib/fdt_dbg.c
+++ b/lib/fdt_dbg.c
@@ -1,3 +1,8 @@
+/**
+ * @file fdt_dbg.c
+ * Dump fdt info to serial.
+ */
+
 #include <apos/debug.h>
 #include <libfdt.h>
 
diff --git a/lib/fdt_empty_tree.c b/lib/fdt_empty_tree.c
index a057358..bdfb9cb 100644
--- a/lib/fdt_empty_tree.c
+++ b/lib/fdt_empty_tree.c
@@ -1,2 +1,7 @@
+/**
+ * @file fdt_empty_tree.c
+ * Wrapper around libfdt/fdt_empty_tree.c, sets up environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt_empty_tree.c"
diff --git a/lib/fdt_ro.c b/lib/fdt_ro.c
index b60a1a8..4528c60 100644
--- a/lib/fdt_ro.c
+++ b/lib/fdt_ro.c
@@ -1,2 +1,7 @@
+/**
+ * @file fdt_ro.c
+ * Wrapper around libfdt/fdt_ro.c, sets up the environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt_ro.c"
diff --git a/lib/fdt_rw.c b/lib/fdt_rw.c
index 1bb8ed4..79e7fa9 100644
--- a/lib/fdt_rw.c
+++ b/lib/fdt_rw.c
@@ -1,2 +1,7 @@
+/**
+ * @file fdt_rw.c
+ * Wrapper around libfdt/fdt_rw.c, sets up the environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt_rw.c"
diff --git a/lib/fdt_strerror.c b/lib/fdt_strerror.c
index f442010..70791b7 100644
--- a/lib/fdt_strerror.c
+++ b/lib/fdt_strerror.c
@@ -1,2 +1,7 @@
+/**
+ * @file fdt_strerror.c
+ * Wrapper around libfdt/fdt_strerror.c, sets up the environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt_strerror.c"
diff --git a/lib/fdt_sw.c b/lib/fdt_sw.c
index b5b1257..5bb8991 100644
--- a/lib/fdt_sw.c
+++ b/lib/fdt_sw.c
@@ -1,2 +1,7 @@
+/**
+ * @file fdt_sw.c
+ * Wrapper around libfdt/fdt_sw.c, sets up the environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt_sw.c"
diff --git a/lib/fdt_wip.c b/lib/fdt_wip.c
index ee3b4d3..e5dab53 100644
--- a/lib/fdt_wip.c
+++ b/lib/fdt_wip.c
@@ -1,2 +1,7 @@
+/**
+ * @file fdt_wip.c
+ * Wrapper around libfdt/fdt_wip.c, sets up the environment.
+ */
+
 #include "libfdt_env.h"
 #include "../dtc/libfdt/fdt_wip.c"
diff --git a/lib/ubsan.c b/lib/ubsan.c
index 7f4df2a..8b103df 100644
--- a/lib/ubsan.c
+++ b/lib/ubsan.c
@@ -1,10 +1,14 @@
+/**
+ * @file ubsan.c
+ * Tiny undefined behaviour sanitizer, mostly lifted from
+ * https://github.com/Abb1x/tinyubsan/blob/master/src/tinyubsan.c
+ *
+ * \todo: Add in more runtime info.
+ */
+
 #include <apos/types.h>
 #include <apos/debug.h>
 
-/* mostly lifted from https://github.com/Abb1x/tinyubsan/blob/master/src/tinyubsan.c */
-/* TODO: while this is really useful, it would probably be a good idea to add in
- * more runtime info, see linux for example */
-
 struct tu_source_location {
 	const char *file;
 	uint32_t line;
diff --git a/scripts/warn-undocumented b/scripts/warn-undocumented
new file mode 100755
index 0000000..78f1401
--- /dev/null
+++ b/scripts/warn-undocumented
@@ -0,0 +1,6 @@
+#!/bin/sh
+# look through all files for either @file or \file, grep -c will report
+# ./example.file:0 if it is not found.
+find arch lib common include -iname '*.[ch]' -exec \
+	grep -c '[@\]file' {} \+ \
+	| awk -F':' '$2 == 0 {print "Undocumented file:", $1}'