rust-lang / nomicon

The Dark Arts of Advanced and Unsafe Rust Programming
https://doc.rust-lang.org/nomicon/
Apache License 2.0
1.79k stars 261 forks source link

Consider using mdbook's include anchors feature for some examples #289

Open JohnTitor opened 3 years ago

JohnTitor commented 3 years ago

@ehuss suggested in https://github.com/rust-lang/nomicon/pull/288#pullrequestreview-696730664:

One possible option in the future is to use {{#rustdoc_include}} (along with mdbook's include anchors), and place the sample code in a separate directory where it can be more thoroughly tested. I notice there are huge chunks of code that aren't tested at all, which means there is a good likelihood that it contains errors, or may become incorrect in the future. TRPL is written this way. A big downside is that it becomes more difficult to edit/read the markdown source since the examples are in a separate file, so it is tough to decide if that is worth it.

I think at least examples using libc crate should be considered here. They're ignored just because requiring an external crate but it would be easy to test if we had it. And some longer examples could also be moved to the external directory to shrink markdown files.