Merge "Explain the header tests better."
diff --git a/README.md b/README.md
index 8d8e583..5107f42 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,9 @@
#### tests/ --- unit tests
The `tests/` directory contains unit tests. Roughly arranged as one file per
-publicly-exported header file.
+publicly-exported header file. `tests/headers/` contains compile-only tests
+that just check that things are _in_ the headers, whereas the "real" tests
+check actual _behavior_.
#### benchmarks/ --- benchmarks
diff --git a/tests/headers/posix/README.md b/tests/headers/posix/README.md
new file mode 100644
index 0000000..e7c171a
--- /dev/null
+++ b/tests/headers/posix/README.md
@@ -0,0 +1,8 @@
+# POSIX header tests
+
+These compile-time tests check that each POSIX header contains _at
+least_ what POSIX says. Every POSIX header file gets a corresponding
+`.c` file in this directory. Every constant, macro, type, struct field,
+and function in the header gets a corresponding assertion in the file.
+
+See `header_checks.h` for the implementation of the assertions.