TRPL: Documentation #22549
TRPL: Documentation #22549
Conversation
|
r? @pcwalton (rust_highfive has picked a reviewer for you, use r? to override) |
|
If doctests pass for this locally, let me know (post review) and I'll include it in the current rollup. |
|
They all pass for me: |
|
Awesome, thanks. Will rollup when this gets an r+ |
| struct Whizbang; | ||
| ~~~ | ||
| Rust keeps track of these comments, and uses them when generating | ||
| documentation. This is important when documenting things like enums: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I've heard people ask about it two or three times, they're not used to comments being anything but 'ignore this'
|
Is the name "Rustdoc" or "rustdoc"? |
|
|
steveklabnik
force-pushed
the
doc_documentation
branch
from
883ae3f to
ccea16d
Compare
|
@huonw largely updated, one or two questions remaining |
|
@huonw ping! |
| Documentation comments are written in Markdown. | ||
|
|
||
| Rust keeps track of these comments, and uses them when generating | ||
| documentation. This is important when documenting things like enums: |
There was a problem hiding this comment.
"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?
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
"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.
| only shows the part you care about. | ||
|
|
||
| ``` | ||
| /// ```should_fail |
There was a problem hiding this comment.
cc #21824
(The description sentence below can probably be updated for that too.)
There was a problem hiding this comment.
Ahh, the description describes exactly why i left it as fail :) Anyway, fixed
|
@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! |
|
steveklabnik
force-pushed
the
doc_documentation
branch
from
d6e4ca2 to
977d789
Compare
This chapter covers writing documentation in depth. Fixes rust-lang#4361 Fixes rust-lang#12862 Fixes rust-lang#14070 Fixes rust-lang#14967
|
@huonw: sounds great. I've fixed that, squashed, and rebased. |
|
@bors r+ |
This chapter covers writing documentation in depth.
Fixes #4361
Fixes #12862
Fixes #14070
Fixes #14967