Document the doc attribute #43792
Document the doc attribute #43792
Conversation
|
r? @frewsxcv (rust_highfive has picked a reviewer for you, use r? to override) |
|
I'm missing /cc @rust-lang/docs |
| its job. | ||
|
|
||
| The most basic job of `#[doc]` is to be the way that the text of the documentation | ||
| is handled. That is, `///` is syntax sugar for `#[doc]`. This means that these two |
There was a problem hiding this comment.
I find this phrasing (and the repetition of "job") really awkward... how about "The most basic function of #[doc] is to handle the actual documentation text."?
|
|
||
| ```rust,ignore | ||
| /// This is a doc comment. | ||
| #[doc = "This is a doc comment."] |
There was a problem hiding this comment.
Note that these are not actually the same! The former has a leading space, but the latter does not. This is why the unindent-comments pass exists, and also is the reason #42760 exists.
| ```rust,ignore | ||
| #[doc = "This is"] | ||
| #[doc = " a "] | ||
| #[doc = "doc comment"] |
There was a problem hiding this comment.
Except collapse-docs will put these all on multiple lines. It's not necessarily the same as ///This is a doc comment, all on one line.
There was a problem hiding this comment.
right, and then it's markdown that makes them all in one line in the final output. whew.
There was a problem hiding this comment.
oh right, markdown joins those lines up anyway >_>;;
There was a problem hiding this comment.
this should be resolved now
| #![doc(html_playground_url = "https://playground.foo.com/")] | ||
| ``` | ||
|
|
||
| Now, when you press "run", the button will make a request to this domain. |
There was a problem hiding this comment.
note that for html_favicon_url, html_logo_url, and html_playground_url, their corresponding items will be missing entirely if they're not given. (i.e. no favicon/no corner logo/no run buttons)
|
|
||
| Since primitive types are defined in the compiler, there's no place to attach documentation | ||
| attributes. This attribute is used by the standard library to provide a way to generate | ||
| documentation for primitive types. |
There was a problem hiding this comment.
When i was adding the new primitive pages, i wondered whether it would be useful for certain extension crates to include their own primitive pages, in case they implement their traits on the primitives. num comes to mind. Would we want to promote this at all? From what i saw of the code, rustdoc doesn't discriminate based on whether the crate is libstd or not, it just looks for them in the root of the crate and generates the page based on what's there.
There was a problem hiding this comment.
it would be useful for certain extension crates to include their own primitive pages,
Hm, I think I'd want to see how this works before advocating for people to use it. Wouldn't this overwrite the usual primitive page?
There was a problem hiding this comment.
What usual primitive page? Some random crate isn't going to include the libstd primitive docs anywhere. I can try this out with num to see how it goes.
There was a problem hiding this comment.
Consider https://docs.rs/mysql/12.0.2/mysql/struct.Row.html#method.len
the return type is usize, it links to usize's primitive page.
There was a problem hiding this comment.
Oh, the links! Yeah, that would totally overwrite those links.
...in fact, it would probably also overwrite those links in any dependent crates, too. I think the thing that populates those links searches from the top down, which means that any overridden links would definitely appear before libstd. Possibly worth investigating, and maybe worth changing, but it's probably not something to encourage in that case. >_>
|
Updated with the |
| This form of the `doc` attribute lets you control the favicon of your docs. | ||
|
|
||
| ```rust,ignore | ||
| #![doc(html_favicon_url = "https://foo.com/favicon.ico")] |
There was a problem hiding this comment.
For example URLs in docs you really should use example.com or one of the domains reserved for this: https://en.wikipedia.org/wiki/Example.com.
| the tracking issue. | ||
|
|
||
| ```rust,ignore | ||
| #![doc(issue_tracker_base_url = "https://github.com/foo/foo/issues/")] |
There was a problem hiding this comment.
Again this should be replaced with https://github.com/rust-lang/rust/issues/ as github.com/foo is a real github account and this attribute is only for std anyway,
| ## `#[doc(hidden)]` | ||
|
|
||
| Any item annotated with `#[doc(hidden)]` will not appear in the documentation, unless | ||
| the `strip-hidden` pass is removed. |
There was a problem hiding this comment.
Ideally, this would link to the section in your other PR, but it depends which PR gets shipped first
There was a problem hiding this comment.
yeah, I think we should worry about intra-linking after all the chapters land
shepmaster
added
the
S-waiting-on-author
|
looks good to me, great addition to the rustdoc book! 🎉 @bors r+ rollup |
|
📌 Commit 1e4aaea has been approved by |
Document the doc attribute cc #42322
|
☀️ Test successful - status-appveyor, status-travis |
cc #42322