rustdoc: Document effect of fundamental types #102661
Conversation
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @jsha (or someone else) soon. Please see the contribution instructions for more information. |
rust-highfive
added
the
S-waiting-on-review
| or in crates that avoid nightly features in general, | ||
| such a type can be marked as fundamental only for purposes of documentation | ||
| by using the annotation `#[cfg_attr(doc, fundamental)]` | ||
| (which is then accompanied by a `#![cfg_attr(doc, feature(fundamental))]` on the crate). |
There was a problem hiding this comment.
Please don't teach people to do that. It breaks locally-built docs for anyone using a stable compiler.
If you just want to mark the type fundamental on docs.rs, use #![cfg_attr(docsrs, feature(fundamental))] and a Cargo.toml line to target docs.rs like this.
There was a problem hiding this comment.
Fair enough (I actually even do that, and went with a simpler version for brevity).
I'm altering the proposal to reflect that (with the docs.rs section simplified to use features = [...], or is there any particular reason why that is not used in the crate you referenced?) -- if that turns out to be more verbose than is practical for the book section, I could remove the play-by-play and replace it with a "such a type can be marked as fundamental only when a feature exclusive to documentation is configured".
There was a problem hiding this comment.
I don't know why some people use feature flags and others use plain cfgs. Either way works fine.
Removing the play-by-play is probably the best choice. Using unstable features in docs without using them while building the code as a library isn't really specific to #[fundamenta]. Any unstable feature could benefit from that.
There was a problem hiding this comment.
Right; it's now reduced to a note that the effects can be limited to documentation build time. (Of the choices between feature and cfg, I've opted to state "feature", as I consider those easier to handle, and there seems not to be explicit guidance toward either).
| but also on the page about `T`. | ||
| In a sense, it makes the type transparent to Rustdoc. | ||
| This is especially convenient for types that work as annotated pointers, | ||
| such as `Pin<&mut T>` or `Rc<T>`, |
There was a problem hiding this comment.
Rc can be a self receiver, but isn't fundamental. The only fundamental types in the standard library are Pin and Box.
There was a problem hiding this comment.
Thanks, I should have checked that. Limited to "such as Pin<...>" now.
|
Should I squash these into a single commit for better history readability? (The detour of having a typo in, or having a more elaborate version are probably not worth persisting). |
|
Yes, please. |
chrysn
force-pushed
the
rustdoc-effect-of-fundamental
branch
from
c480396 to
31bc385
Compare
|
Squashed with identical tree, and updated. |
|
@bors r+ rollup |
bors
added
S-waiting-on-bors
…t-of-fundamental, r=notriddle rustdoc: Document effect of fundamental types This was implemented in rust-lang#96565, but not documented. But it's a useful feature for everyone who implements own wrapper (especially wrappers-around-pointers) types, so that they can behave like pointers (and stdlib wrappers) do -- so here goes a mention in the unstable section of the rustdoc book. (That is where I initially looked to find tricks for making my own wrapper types be transparent to documentation).
…t-of-fundamental, r=notriddle rustdoc: Document effect of fundamental types This was implemented in rust-lang#96565, but not documented. But it's a useful feature for everyone who implements own wrapper (especially wrappers-around-pointers) types, so that they can behave like pointers (and stdlib wrappers) do -- so here goes a mention in the unstable section of the rustdoc book. (That is where I initially looked to find tricks for making my own wrapper types be transparent to documentation).
…t-of-fundamental, r=notriddle rustdoc: Document effect of fundamental types This was implemented in rust-lang#96565, but not documented. But it's a useful feature for everyone who implements own wrapper (especially wrappers-around-pointers) types, so that they can behave like pointers (and stdlib wrappers) do -- so here goes a mention in the unstable section of the rustdoc book. (That is where I initially looked to find tricks for making my own wrapper types be transparent to documentation).
Rollup of 8 pull requests Successful merges: - rust-lang#99818 (don't ICE when normalizing closure input tys) - rust-lang#102514 (Don't repeat lifetime names from outer binder in print) - rust-lang#102661 (rustdoc: Document effect of fundamental types) - rust-lang#102782 (Add regression test for rust-lang#102124) - rust-lang#102790 (Fix llvm-tblgen for cross compiling) - rust-lang#102807 (Document `rust-docs-json` component) - rust-lang#102812 (Remove empty core::lazy and std::lazy) - rust-lang#102818 (Clean up rustdoc highlight.rs imports a bit) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
This was implemented in #96565, but not documented. But it's a useful feature for everyone who implements own wrapper (especially wrappers-around-pointers) types, so that they can behave like pointers (and stdlib wrappers) do -- so here goes a mention in the unstable section of the rustdoc book.
(That is where I initially looked to find tricks for making my own wrapper types be transparent to documentation).