TRPL: Documentation

[steveklabnik]

This chapter covers writing documentation in depth.

Fixes#4361
Fixes#12862
Fixes#14070
Fixes#14967

[rust-highfive]

r? @pcwalton

(rust_highfive has picked a reviewer for you, use r? to override)

[Manishearth]

If doctests pass for this locally, let me know (post review) and I'll include it in the current rollup.

[steveklabnik]

They all pass for me:

$ rustdoc --test src/doc/trpl/documentation.md running 32 tests
test _0 ... ignored
test _10 ... ok
test _1 ... ok
test _11 ... ok
test _12 ... ok
test _13 ... ok
test _16 ... ok
test _14 ... ok
test _15 ... ok
test _2 ... ignored
test _17 ... ok
test _19 ... ok
test _18 ... ok
test _20 ... ok
test _21 ... ok
test _22 ... ok
test _23 ... ok
test _24 ... ok
test _25 ... ok
test _29 ... ignored
test _27 ... ok
test _30 ... ignored
test _28 ... ok
test _26 ... ok
test _3 ... ok
test _31 ... ok
test _5 ... ok
test _4 ... ok
test _6 ... ok
test _7 ... ok
test _8 ... ok
test _9 ... ok
test result: ok. 28 passed; 0 failed; 4 ignored; 0 measured

[Manishearth]

Awesome, thanks. Will rollup when this gets an r+

[huonw]

This enum example seems to be placed very prominently for something of an edge case? Maybe I'm missing how often it occurs.

Also, it's not not clear to me what "this" is and how it interacts with the position of doc-comments.

[steveklabnik]

I've heard people ask about it two or three times, they're not used to comments being anything but 'ignore this'

[huonw]

Is the name "Rustdoc" or "rustdoc"?

[steveklabnik]

rustdoc

[steveklabnik]

@huonw largely updated, one or two questions remaining

[steveklabnik]

@huonw ping!

[huonw]

"document"/"documentation" has been said a lot in the three paragraphs from line 35 to this one; maybe things could be tweaked to be a little more streamlined?

[huonw]

Also, I'm still unsure what "this" is here? (It's not clear to me why rust keeping track of the comments is important for enums in particular.)

[steveklabnik]

"This" refers to the previous sentence: Rust understanding comments, rather than just ignoring them. I don't think most languages have documentation-specific comments, this behavior is different than people expect.