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.

[huonw]

cc #21824

(The description sentence below can probably be updated for that too.)

[steveklabnik]

Ahh, the description describes exactly why i left it as fail :) Anyway, fixed

[steveklabnik]

@huonw updated for everything but the panic change. Maybe you could suggest some language you're happy with? :) I'd like to get this wrapped up!

[huonw]

Unrecoverable misuses of a function (i.e. programming errors) in Rust are usually indicated by panics, which kill the whole current thread at the very least. If your function has a non-trivial contract like this, that is detected/enforced by panics, documenting it is very important:

[steveklabnik]

@huonw: sounds great. I've fixed that, squashed, and rebased.

[huonw]

@bors r+

[bors]

@bors r=huonw 977d789

[bors]

⌛ Testing commit 977d789 with merge 36cd65f...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-32-nopt-t, auto-win-32-opt, auto-win-64-nopt-t, auto-win-64-opt