debuginfo test suite needs more documentation

The docs for the debuginfo test suite are quite brief, consisting basically just of a single example. Even that example leasves me more confused than enlightened:

For example, the following will build the test, start the debugger, set a breakpoint, launch the program, inspect a value, and check what the debugger prints:

The #break comment is below the other comments in the file. So apparently something is going on here with the execution order of these comments that makes them not just top-to-bottom in the file?

Also, #break is not the only directive that can start with #. Apparently there's also #locN:
https://github.com/rust-lang/rust/blob/70320c1936e2cdf0dd4f79c6539b32dd928d4cc2/tests/debuginfo/macro-stepping.rs#L111
No idea what that does.

Also, keep in mind that whoever hits a test failure in a debuginfo test may have never used gdb or a tool like it. The documentation should either give them some chance to fix the test, or tell them whom to ping for help.

Start with the debuginfo tests section of the rustc-dev-guide and compare its example with tests/debuginfo/macro-stepping.rs, especially the #break and #locN directives. Document directive execution order, explain the referenced directives and debugger expectations, and include enough guidance for investigating failures.