diff --git a/src/tests/headers.md b/src/tests/headers.md
index 143f375c1..1f2474aa0 100644
--- a/src/tests/headers.md
+++ b/src/tests/headers.md
@@ -5,7 +5,7 @@
 Header commands are special comments that tell compiletest how to build and
 interpret a test.
 They must appear before the Rust source in the test.
-They may also appear in legacy Makefiles for
+They may also appear in `rmake.rs` or legacy Makefiles for
 [run-make tests](compiletest.md#run-make-tests).
 
 They are normally put after the short comment that explains the point of this test.
@@ -27,6 +27,10 @@ fn main() {
 Header commands can be standalone (like `//@ run-pass`) or take a value (like
 `//@ compile-flags: -C overflow-checks=off`).
 
+Header commands are written with one header per line: you cannot write multiple
+headers on the same line. For example, if you write `//@ only-x86 only-windows`
+then `only-windows` is interpreted as a comment, not a separate directive.
+
 ## Header commands
 
 The following is a list of header commands.