about summary refs log tree commit diff
path: root/src/doc/rustdoc
AgeCommit message (Collapse)AuthorLines
2022-03-10Rollup merge of #93950 - T-O-R-U-S:use-modern-formatting-for-format!-macros, ↵Dylan DPC-1/+1
r=Mark-Simulacrum Use modern formatting for format! macros This updates the standard library's documentation to use the new format_args syntax. The documentation is worthwhile to update as it should be more idiomatic (particularly for features like this, which are nice for users to get acquainted with). The general codebase is likely more hassle than benefit to update: it'll hurt git blame, and generally updates can be done by folks updating the code if (and when) that makes things more readable with the new format. A few places in the compiler and library code are updated (mostly just due to already having been done when this commit was first authored). `eprintln!("{}", e)` becomes `eprintln!("{e}")`, but `eprintln!("{}", e.kind())` remains untouched.
2022-03-10Use implicit capture syntax in format_argsT-O-R-U-S-1/+1
This updates the standard library's documentation to use the new syntax. The documentation is worthwhile to update as it should be more idiomatic (particularly for features like this, which are nice for users to get acquainted with). The general codebase is likely more hassle than benefit to update: it'll hurt git blame, and generally updates can be done by folks updating the code if (and when) that makes things more readable with the new format. A few places in the compiler and library code are updated (mostly just due to already having been done when this commit was first authored).
2022-03-09Improve rustdoc bookLoïc BRANSTETT-83/+106
2022-03-04Rollup merge of #93418 - ojeda:no-shortcut, r=camelidDylan DPC-1/+1
rustdoc & doc: no `shortcut` for `rel="icon"` According to https://html.spec.whatwg.org/multipage/links.html#rel-icon: > For historical reasons, the `icon` keyword may be preceded by the keyword "`shortcut`". And to https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types: > **Warning:** The `shortcut` link type is often seen before `icon`, but this link type is non-conforming, ignored and **web authors must not use it anymore.** While it was removed from the Rust logo case a while ago in commit 085679c ("Use theme-adaptive SVG favicon from other Rust sites"), it is still there for the custom logo case. Also updated a few other instances. Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
2022-02-28Rollup merge of #93413 - lsimons:patch-1, r=Dylan-DPCMatthias Krüger-1/+1
Fix broken link from rustdoc docs to ayu theme
2022-02-25Add documentation for `--check-cfg` in rustdoc bookLoïc BRANSTETT-0/+14
2022-02-18Rollup merge of #93497 - willcrichton:rustdoc-scrape-test, r=GuillaumeGomezMatthias Krüger-0/+3
Pass `--test` flag through rustdoc to rustc so `#[test]` functions can be scraped As a part of stabilizing the scrape examples extension in Cargo, I uncovered a bug where examples cannot be scraped from tests. See this test: https://github.com/rust-lang/cargo/pull/10343/files#diff-27aa4f012ebfebaaee61498d91d2370de460628405d136b05e77efe61e044679R2496 The issue is that when rustdoc is run on a test file, because `--test` is not passed as a rustc option, then functions annotated with `#[test]` are ignored by the compiler. So this PR changes rustdoc so when `--test` is passed in conjunction with a `--scrape-example-<suffix>` flag, then the `test` field of `rustc_interface::Config` is true. r? `@camelid`
2022-02-15Add documentation for rustdoc --check optionGuillaume Gomez-0/+11
2022-02-15Clean up rustdoc command line args docGuillaume Gomez-1/+3
2022-02-11Add --scrape-tests flags so rustdoc can scrape examples from testsWill Crichton-0/+3
2022-01-28rustdoc: no `shortcut` in `rel="icon"`Miguel Ojeda-1/+1
According to https://html.spec.whatwg.org/multipage/links.html#rel-icon: > For historical reasons, the `icon` keyword may be preceded by > the keyword "`shortcut`". And to https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types: > **Warning:** The `shortcut` link type is often seen before `icon`, > but this link type is non-conforming, ignored and **web authors > must not use it anymore.** While it was removed from the Rust logo case a while ago in commit 085679c8414 ("Use theme-adaptive SVG favicon from other Rust sites"), it is still there for the custom logo case. Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
2022-01-28Fix broken link from rustdoc docs to ayu themeLeo Simons-1/+1
2022-01-28fix typo `documenation`Kvicii-1/+1
2022-01-27fix typo `documenation`Kvicii-1/+1
2022-01-14Rollup merge of #92818 - GuillaumeGomez:update-doc-cfg-doc, r=camelidMatthias Krüger-0/+33
Update documentation for doc_cfg feature Fixes #92484.
2022-01-13Update documentation for doc_cfgGuillaume Gomez-0/+33
2022-01-09Extended the note on the use of `no_run` attributeDmitrii - Demenev-1/+2
2021-12-11Rollup merge of #91310 - hi-rustin:rustin-patch-rustdoc, r=jyn514Matthias Krüger-2/+2
Add --out-dir flag for rustdoc part of https://github.com/rust-lang/rust/issues/91260 Add --out-dir flag for rustdoc and change the `-o` option to point to out-dir. I'm not quite sure if it should be stable, also I'm not sure if this parameter priority is appropriate? Or should I just refuse to pass both parameters at the same time? r? `@jyn514`
2021-12-06Link to rustdoc_json_types docs instead of rustdoc-json RFCNixon Enraght-Moony-1/+1
2021-12-05Update doc about code block edition attributesr00ster-3/+2
2021-11-30Add --out-dir flag for rustdochi-rustin-2/+2
Signed-off-by: hi-rustin <rustin.liu@gmail.com>
2021-11-26Remove `--display-doctest-warnings`Joshua Nelson-16/+10
This can be replicated in full with other existing features, there's no need to have a separate option for it. This also fixes a bug where `--test-args=--show-output` had no effect, and updates the documentation.
2021-11-24Rollup merge of #90420 - GuillaumeGomez:rustdoc-internals-feature, r=camelidGuillaume Gomez-2/+3
Create rustdoc_internals feature gate As suggested by ``@camelid`` [here](https://github.com/rust-lang/rust/pull/90398#issuecomment-955093851), since `doc_keyword` and `doc_primitive` aren't meant to be stabilized, we could put them behind a same feature flag. This is pretty much what it would look like (needs to update the tests too). The tracking issue is https://github.com/rust-lang/rust/issues/90418. What do you think ``@rust-lang/rustdoc`` ?
2021-11-24Create rustdoc_internals feature gateGuillaume Gomez-2/+3
2021-11-19Put back removed empty lineGuillaume Gomez-0/+1
2021-11-18Clean up mess for --show-coverage documentationGuillaume Gomez-40/+33
2021-11-05Add a chapter on reading Rustdoc outputLeonora Tindall-0/+108
Includes documentation for: - general page structure - navigation - searching - themes - deep-linking Doesn't include docs on the settings page.
2021-11-01Rollup merge of #90398 - GuillaumeGomez:doc-keyword-doc, r=camelidMatthias Krüger-2/+20
Document `doc(keyword)` unstable attribute r? `@camelid`
2021-10-31Add doc about doc(keyword) unstable attributeGuillaume Gomez-2/+20
2021-10-29Unify titles in rustdoc book doc attributes chapterGuillaume Gomez-2/+6
2021-10-28Add missing documentation for doc aliasGuillaume Gomez-2/+49
2021-10-22Revert def_id addition from clean::Function, add test forWill Crichton-2/+12
scrape-examples options
2021-10-19Small scrape-example fixesWill Crichton-1/+1
2021-10-06Update to latest rustc and rustdoc stylesWill Crichton-0/+14
2021-10-02Fix typos in rustdoc/lintsTobias Nießen-3/+3
Refs: https://github.com/rust-lang/rust/pull/85223
2021-10-01Rollup merge of #85223 - simbleau:master, r=steveklabnikManish Goregaokar-0/+6
rustdoc: Clarified the attribute which prompts the warning The example call was lacking clarification of the `#![warn(rustdoc::invalid_codeblock_attributes)]` attribute which generates the specified warning.
2021-09-21Fix inconsistent heading level in the rustdoc bookNoah Lev-1/+1
2021-09-21Document `--show-type-layout` in the rustdoc bookNoah Lev-0/+16
2021-09-14Rename --display-warnings to --display-doctest-warningsGuillaume Gomez-3/+3
2021-08-16feature gate doc(primitive)Joshua Nelson-6/+7
2021-08-09Clarify terms in rustdoc bookKlim Tsoutsman-22/+24
Change code blocks to Rust
2021-08-02Auto merge of #87535 - lf-:authors, r=Mark-Simulacrumbors-1/+0
rfc3052 followup: Remove authors field from Cargo manifests Since RFC 3052 soft deprecated the authors field, hiding it from crates.io, docs.rs, and making Cargo not add it by default, and it is not generally up to date/useful information for contributors, we may as well remove it from crates in this repo.
2021-07-30Fix missing word in commentWilfred Hughes-1/+1
2021-07-29rfc3052: Remove authors field from Cargo manifestsJade-1/+0
Since RFC 3052 soft deprecated the authors field anyway, hiding it from crates.io, docs.rs, and making Cargo not add it by default, and it is not generally up to date/useful information, we should remove it from crates in this repo.
2021-07-18Add doc for --nocaptureGuillaume Gomez-0/+7
2021-06-27Add Website features page to rustdoc bookJean-Luc Thumm-0/+26
2021-06-04Remove `doc(include)`Joshua Nelson-19/+1
2021-05-25Fix tasklist example in rustdoc book.Eric Huss-6/+4
2021-05-18Rollup merge of #83366 - jyn514:stabilize-key-value-attrs, r=petrochenkovJack Huey-0/+12
Stabilize extended_key_value_attributes Closes https://github.com/rust-lang/rust/issues/44732. Closes https://github.com/rust-lang/rust/issues/78835. Closes https://github.com/rust-lang/rust/issues/82768 (by making it irrelevant). # Stabilization report ## Summary This stabilizes using macro expansion in key-value attributes, like so: ```rust #[doc = include_str!("my_doc.md")] struct S; #[path = concat!(env!("OUT_DIR"), "/generated.rs")] mod m; ``` See Petrochenkov's excellent blog post [on internals](https://internals.rust-lang.org/t/macro-expansion-points-in-attributes/11455) for alternatives that were considered and rejected ("why accept no more and no less?") This has been available on nightly since 1.50 with no major issues. ## Notes ### Accepted syntax The parser accepts arbitrary Rust expressions in this position, but any expression other than a macro invocation will ultimately lead to an error because it is not expected by the built-in expression forms (e.g., `#[doc]`). Note that decorators and the like may be able to observe other expression forms. ### Expansion ordering Expansion of macro expressions in "inert" attributes occurs after decorators have executed, analogously to macro expressions appearing in the function body or other parts of decorator input. There is currently no way for decorators to accept macros in key-value position if macro expansion must be performed before the decorator executes (if the macro can simply be copied into the output for later expansion, that can work). ## Test cases - https://github.com/rust-lang/rust/blob/master/src/test/ui/attributes/key-value-expansion-on-mac.rs - https://github.com/rust-lang/rust/blob/master/src/test/rustdoc/external-doc.rs The feature has also been dogfooded extensively in the compiler and standard library: - https://github.com/rust-lang/rust/pull/83329 - https://github.com/rust-lang/rust/pull/83230 - https://github.com/rust-lang/rust/pull/82641 - https://github.com/rust-lang/rust/pull/80534 ## Implementation history - Initial proposal: https://github.com/rust-lang/rust/issues/55414#issuecomment-554005412 - Experiment to see how much code it would break: https://github.com/rust-lang/rust/pull/67121 - Preliminary work to restrict expansion that would conflict with this feature: https://github.com/rust-lang/rust/pull/77271 - Initial implementation: https://github.com/rust-lang/rust/pull/78837 - Fix for an ICE: https://github.com/rust-lang/rust/pull/80563 ## Unresolved Questions ~~https://github.com/rust-lang/rust/pull/83366#issuecomment-805180738 listed some concerns, but they have been resolved as of this final report.~~ ## Additional Information There are two workarounds that have a similar effect for `#[doc]` attributes on nightly. One is to emulate this behavior by using a limited version of this feature that was stabilized for historical reasons: ```rust macro_rules! forward_inner_docs { ($e:expr => $i:item) => { #[doc = $e] $i }; } forward_inner_docs!(include_str!("lib.rs") => struct S {}); ``` This also works for other attributes (like `#[path = concat!(...)]`). The other is to use `doc(include)`: ```rust #![feature(external_doc)] #[doc(include = "lib.rs")] struct S {} ``` The first works, but is non-trivial for people to discover, and difficult to read and maintain. The second is a strange special-case for a particular use of the macro. This generalizes it to work for any use case, not just including files. I plan to remove `doc(include)` when this is stabilized (https://github.com/rust-lang/rust/pull/82539). The `forward_inner_docs` workaround will still compile without warnings, but I expect it to be used less once it's no longer necessary.
2021-05-18Stabilize extended_key_value_attributesJoshua Nelson-0/+12
# Stabilization report ## Summary This stabilizes using macro expansion in key-value attributes, like so: ```rust #[doc = include_str!("my_doc.md")] struct S; #[path = concat!(env!("OUT_DIR"), "/generated.rs")] mod m; ``` See the changes to the reference for details on what macros are allowed; see Petrochenkov's excellent blog post [on internals](https://internals.rust-lang.org/t/macro-expansion-points-in-attributes/11455) for alternatives that were considered and rejected ("why accept no more and no less?") This has been available on nightly since 1.50 with no major issues. ## Notes ### Accepted syntax The parser accepts arbitrary Rust expressions in this position, but any expression other than a macro invocation will ultimately lead to an error because it is not expected by the built-in expression forms (e.g., `#[doc]`). Note that decorators and the like may be able to observe other expression forms. ### Expansion ordering Expansion of macro expressions in "inert" attributes occurs after decorators have executed, analogously to macro expressions appearing in the function body or other parts of decorator input. There is currently no way for decorators to accept macros in key-value position if macro expansion must be performed before the decorator executes (if the macro can simply be copied into the output for later expansion, that can work). ## Test cases - https://github.com/rust-lang/rust/blob/master/src/test/ui/attributes/key-value-expansion-on-mac.rs - https://github.com/rust-lang/rust/blob/master/src/test/rustdoc/external-doc.rs The feature has also been dogfooded extensively in the compiler and standard library: - https://github.com/rust-lang/rust/pull/83329 - https://github.com/rust-lang/rust/pull/83230 - https://github.com/rust-lang/rust/pull/82641 - https://github.com/rust-lang/rust/pull/80534 ## Implementation history - Initial proposal: https://github.com/rust-lang/rust/issues/55414#issuecomment-554005412 - Experiment to see how much code it would break: https://github.com/rust-lang/rust/pull/67121 - Preliminary work to restrict expansion that would conflict with this feature: https://github.com/rust-lang/rust/pull/77271 - Initial implementation: https://github.com/rust-lang/rust/pull/78837 - Fix for an ICE: https://github.com/rust-lang/rust/pull/80563 ## Unresolved Questions ~~https://github.com/rust-lang/rust/pull/83366#issuecomment-805180738 listed some concerns, but they have been resolved as of this final report.~~ ## Additional Information There are two workarounds that have a similar effect for `#[doc]` attributes on nightly. One is to emulate this behavior by using a limited version of this feature that was stabilized for historical reasons: ```rust macro_rules! forward_inner_docs { ($e:expr => $i:item) => { #[doc = $e] $i }; } forward_inner_docs!(include_str!("lib.rs") => struct S {}); ``` This also works for other attributes (like `#[path = concat!(...)]`). The other is to use `doc(include)`: ```rust #![feature(external_doc)] #[doc(include = "lib.rs")] struct S {} ``` The first works, but is non-trivial for people to discover, and difficult to read and maintain. The second is a strange special-case for a particular use of the macro. This generalizes it to work for any use case, not just including files. I plan to remove `doc(include)` when this is stabilized. The `forward_inner_docs` workaround will still compile without warnings, but I expect it to be used less once it's no longer necessary.
generated by cgit-pink 1.4.1-3-g733a5 (git 2.37.1) at 2026-02-25 14:34:11 +0000