diff --git a/src/tests/compiletest.md b/src/tests/compiletest.md
index 129c6a1c5e3e1..46dfe1c0095fc 100644
--- a/src/tests/compiletest.md
+++ b/src/tests/compiletest.md
@@ -160,7 +160,7 @@ the current revision name.
 For example, this will run twice, simulating changing a function:
 
 ```rust,ignore
-// revisions: rpass1 rpass2
+//@ revisions: rpass1 rpass2
 
 #[cfg(rpass1)]
 fn foo() {
@@ -224,11 +224,11 @@ breakpoint, launch the program, inspect a value, and check what the debugger
 prints:
 
 ```rust,ignore
-// compile-flags: -g
+//@ compile-flags: -g
 
-// lldb-command: run
-// lldb-command: print foo
-// lldb-check: $0 = 123
+//@ lldb-command: run
+//@ lldb-command: print foo
+//@ lldb-check: $0 = 123
 
 fn main() {
     let foo = 123;
@@ -480,7 +480,7 @@ There are two [headers](headers.md) to assist with that:
 The source file should be in a directory called `auxiliary` beside the test file.
 
 ```rust,ignore
-// aux-build: my-helper.rs
+//@ aux-build: my-helper.rs
 
 extern crate my_helper;
 // ... You can use my_helper.
@@ -507,8 +507,8 @@ Place the proc-macro itself in a file like `auxiliary/my-proc-macro.rs`
 with the following structure:
 
 ```rust,ignore
-// force-host
-// no-prefer-dynamic
+//@ force-host
+//@ no-prefer-dynamic
 
 #![crate_type = "proc-macro"]
 
@@ -529,7 +529,7 @@ The `#![crate_type]` attribute is needed to specify the correct crate-type.
 Then in your test, you can build with `aux-build`:
 
 ```rust,ignore
-// aux-build: my-proc-macro.rs
+//@ aux-build: my-proc-macro.rs
 
 extern crate my_proc_macro;
 
@@ -545,7 +545,7 @@ Revisions allow a single test file to be used for multiple tests.
 This is done by adding a special header at the top of the file:
 
 ```rust,ignore
-// revisions: foo bar baz
+//@ revisions: foo bar baz
 ```
 
 This will result in the test being compiled (and tested) three times,
@@ -560,7 +560,7 @@ comment, like so:
 
 ```rust,ignore
 // A flag to pass in only for cfg `foo`:
-//[foo]compile-flags: -Z verbose
+//@[foo]compile-flags: -Z verbose
 
 #[cfg(foo)]
 fn test_foo() {
diff --git a/src/tests/headers.md b/src/tests/headers.md
index 649ea62eb0565..20771683666b6 100644
--- a/src/tests/headers.md
+++ b/src/tests/headers.md
@@ -8,15 +8,14 @@ They must appear before the Rust source in the test.
 They may also appear in 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.
-Some test suites use `//@` to signal that a comment is a header, but most are still
-just using plain comments.
-For example, this test uses the `// compile-flags` command to specify a custom
+Compiletest test suites use `//@` to signal that a comment is a header.
+For example, this test uses the `//@ compile-flags` command to specify a custom
 flag to give to rustc when the test is compiled:
 
 ```rust,ignore
 // Test the behavior of `0 - 1` when overflow checks are disabled.
 
-// compile-flags: -C overflow-checks=off
+//@ compile-flags: -C overflow-checks=off
 
 fn main() {
     let x = 0 - 1;
@@ -24,8 +23,8 @@ fn main() {
 }
 ```
 
-Header commands can be standalone (like `// run-pass`) or take a value (like
-`// compile-flags: -C overflow-checks=off`).
+Header commands can be standalone (like `//@ run-pass`) or take a value (like
+`//@ compile-flags: -C overflow-checks=off`).
 
 ## Header commands
 
@@ -192,10 +191,10 @@ The following headers are generally available, and not specific to particular
 test suites.
 
 * `compile-flags` passes extra command-line args to the compiler,
-  e.g. `// compile-flags: -g` which forces debuginfo to be enabled.
+  e.g. `//@ compile-flags: -g` which forces debuginfo to be enabled.
 * `run-flags` passes extra args to the test if the test is to be executed.
 * `edition` controls the edition the test should be compiled with
-  (defaults to 2015). Example usage: `// edition:2018`.
+  (defaults to 2015). Example usage: `//@ edition:2018`.
 * `failure-status` specifies the numeric exit code that should be expected for
   tests that expect an error.
   If this is not set, the default is 1.
@@ -239,7 +238,7 @@ For example, if you need to pass a compiler flag with a path to a specific
 file, something like the following could work:
 
 ```rust,ignore
-// compile-flags: --remap-path-prefix={{src-base}}=/the/src
+//@ compile-flags: --remap-path-prefix={{src-base}}=/the/src
 ```
 
 Where the sentinel `{{src-base}}` will be replaced with the appropriate path
@@ -285,8 +284,8 @@ also in [`src/tools/compiletest/src/header.rs`] (note that the `Config`
 struct's declaration block is found in [`src/tools/compiletest/src/common.rs`]).
 `TestProps`'s `load_from()` method will try passing the current line of text to
 each parser, which, in turn typically checks to see if the line begins with a
-particular commented (`//`) header command such as `// must-compile-successfully`
-or `// failure-status`. Whitespace after the comment marker is optional.
+particular commented (`//@`) header command such as `//@ must-compile-successfully`
+or `//@ failure-status`. Whitespace after the comment marker is optional.
 
 Parsers will override a given header command property's default value merely by
 being specified in the test file as a header command or by having a parameter