The text of the guide should not be included as code comments

[spastorino]

For instance, here https://rustc-dev-guide.rust-lang.org/compiler-debugging.html#getting-a-backtrace-for-errors we have a comment that says $ # Now, where does the error above come from? I guess we should take that out from comments and place that into regular text. There are probably more uses like that.

[camelid]

That specific case was fixed in #992, though I imagine there are some cases remaining.

[zahash]

do any of these qualify?

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/profiling.md#:~:text=%23%20On%20a%20normal%20crate%20you%20could%20now%20run%20%60cargo%20llvm%2Dlines%60%2C%20but%20%60x%60%20isn%27t%20normal%20%3AP

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/profiling.md#:~:text=%23%20A%20debug%20build%20takes%20_a%20third_%20as%20long%20on%20my%20machine%2C

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/rustdoc-internals.md#:~:text=%23%20The%20documentation%20has%20been%20generated%20into%20%60build/%5BYOUR%20ARCH%5D/doc%60.

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/tracing.md#:~:text=%23%20This%20puts%20the%20output%20of%20all%20debug%20calls%20in%20%60rustc_middle/src/traits%60%20into

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/tracing.md#:~:text=%23%20The%20%60%2DR%60%20switch%20tells%20less%20to%20print%20ANSI%20colors%20without%20escaping%20them.

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/backend/debugging.md#:~:text=%23%20Indicates%20whether%20the%20LLVM%20assertions%20are%20enabled%20or%20not

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/building/how-to-build-and-run.md#:~:text=%23%20On%20a%20Unix%20shell%20if%20you%20don%27t%20have%20the%20necessary%20%60python3%60%20command

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/building/suggested.md#:~:text=//%20.vscode/tasks.json

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/building/suggested.md#:~:text=%23%20This%20file%20contains%20a%20development%20shell%20for%20working%20on%20rustc.

https://github.com/rust-lang/rustc-dev-guide/blob/master/src/profiling/with_perf.md#:~:text=%23%20Setup%3A%20first%20clean%20out%20any%20old%20results%20and%20build%20the%20dependencies%3A

[tshepang]

It would be a pain, and noisy, removing those (saw about half of them) comments and making them normal text.

[jieyouxu]

Triage: I don't think this is always desirable because IMO sometimes inline code comments are better as inline code comments than as part of the prose. Obviously context-dependent.