| Age | Commit message (Collapse) | Author | Lines |
|---|
|
I moved some local arguments and options to either the local options
struct or, if it made sense, the global options struct.
|
|
This was used to get the line number of the first line from the current
docstring, which was then used together with an offset within the
docstring. It's simpler to just pass the offset to the visitor and have
it do the math because it's clearer and this calculation only needs to
be done in one place (the Rust doctest visitor).
|
|
The new name more accurately captures what it is.
|
|
|
|
|
|
|
|
|
|
GuillaumeGomez:stabilize-custom_code_classes_in_docs, r=rustdoc
Stabilize `custom_code_classes_in_docs` feature
Fixes #79483.
This feature has been around for quite some time now, I think it's fine to stabilize it now.
## Summary
## What is the feature about?
In short, this PR changes two things, both related to codeblocks in doc comments in Rust documentation:
* Allow to disable generation of `language-*` CSS classes with the `custom` attribute.
* Add your own CSS classes to a code block so that you can use other tools to highlight them.
#### The `custom` attribute
Let's start with the new `custom` attribute: it will disable the generation of the `language-*` CSS class on the generated HTML code block. For example:
```rust
/// ```custom,c
/// int main(void) {
/// return 0;
/// }
/// ```
```
The generated HTML code block will not have `class="language-c"` because the `custom` attribute has been set. The `custom` attribute becomes especially useful with the other thing added by this feature: adding your own CSS classes.
#### Adding your own CSS classes
The second part of this feature is to allow users to add CSS classes themselves so that they can then add a JS library which will do it (like `highlight.js` or `prism.js`), allowing to support highlighting for other languages than Rust without increasing burden on rustdoc. To disable the automatic `language-*` CSS class generation, you need to use the `custom` attribute as well.
This allow users to write the following:
```rust
/// Some code block with `{class=language-c}` as the language string.
///
/// ```custom,{class=language-c}
/// int main(void) {
/// return 0;
/// }
/// ```
fn main() {}
```
This will notably produce the following HTML:
```html
<pre class="language-c">
int main(void) {
return 0;
}</pre>
```
Instead of:
```html
<pre class="rust rust-example-rendered">
<span class="ident">int</span> <span class="ident">main</span>(<span class="ident">void</span>) {
<span class="kw">return</span> <span class="number">0</span>;
}
</pre>
```
To be noted, we could have written `{.language-c}` to achieve the same result. `.` and `class=` have the same effect.
One last syntax point: content between parens (`(like this)`) is now considered as comment and is not taken into account at all.
In addition to this, I added an `unknown` field into `LangString` (the parsed code block "attribute") because of cases like this:
```rust
/// ```custom,class:language-c
/// main;
/// ```
pub fn foo() {}
```
Without this `unknown` field, it would generate in the DOM: `<pre class="language-class:language-c language-c">`, which is quite bad. So instead, it now stores all unknown tags into the `unknown` field and use the first one as "language". So in this case, since there is no unknown tag, it'll simply generate `<pre class="language-c">`. I added tests to cover this.
EDIT(camelid): This description is out-of-date. Using `custom,class:language-c` will generate the output `<pre class="language-class:language-c">` as would be expected; it treats `class:language-c` as just the name of a language (similar to the langstring `c` or `js` or what have you) since it does not use the designed class syntax.
Finally, I added a parser for the codeblock attributes to make it much easier to maintain. It'll be pretty easy to extend.
As to why this syntax for adding attributes was picked: it's [Pandoc's syntax](https://pandoc.org/MANUAL.html#extension-fenced_code_attributes). Even if it seems clunkier in some cases, it's extensible, and most third-party Markdown renderers are smart enough to ignore Pandoc's brace-delimited attributes (from [this comment](https://github.com/rust-lang/rust/pull/110800#issuecomment-1522044456)).
r? `@notriddle`
|
|
r=compiler-errors
Rename HIR `TypeBinding` to `AssocItemConstraint` and related cleanup
Rename `hir::TypeBinding` and `ast::AssocConstraint` to `AssocItemConstraint` and update all items and locals using the old terminology.
Motivation: The terminology *type binding* is extremely outdated. "Type bindings" not only include constraints on associated *types* but also on associated *constants* (feature `associated_const_equality`) and on RPITITs of associated *functions* (feature `return_type_notation`). Hence the word *item* in the new name. Furthermore, the word *binding* commonly refers to a mapping from a binder/identifier to a "value" for some definition of "value". Its use in "type binding" made sense when equality constraints (e.g., `AssocTy = Ty`) were the only kind of associated item constraint. Nowadays however, we also have *associated type bounds* (e.g., `AssocTy: Bound`) for which the term *binding* doesn't make sense.
---
Old terminology (HIR, rustdoc):
```
`TypeBinding`: (associated) type binding
├── `Constraint`: associated type bound
└── `Equality`: (associated) equality constraint (?)
├── `Ty`: (associated) type binding
└── `Const`: associated const equality (constraint)
```
Old terminology (AST, abbrev.):
```
`AssocConstraint`
├── `Bound`
└── `Equality`
├── `Ty`
└── `Const`
```
New terminology (AST, HIR, rustdoc):
```
`AssocItemConstraint`: associated item constraint
├── `Bound`: associated type bound
└── `Equality`: associated item equality constraint OR associated item binding (for short)
├── `Ty`: associated type equality constraint OR associated type binding (for short)
└── `Const`: associated const equality constraint OR associated const binding (for short)
```
r? compiler-errors
|
|
|
|
Almost all callers want this anyway, and now we can use it to also return fed bodies
|
|
rustdoc: Clarify const-stability with regard to normal stability
Fixes #125511.
- Elide const-unstable if also unstable overall
- Show "const" for const-unstable if also overall unstable
|
|
If a const function is unstable overall (and thus, in all circumstances
I know of, also const-unstable), we should show the option to use it as
const. You need to enable a feature to use the function at all anyway.
If the function is stabilized without also being const-stabilized, then
we do not show the const keyword and instead show "const: unstable" in
the version info.
|
|
It's confusing because if a function is unstable overall, there's no
need to highlight the constness is also unstable. Technically, these
attributes (overall stability and const-stability) are separate, but in
practice, we don't even show the const-unstable's feature flag (it's
normally the same as the overall function).
|
|
* instead simply set the primary message inside the lint decorator functions
* it used to be this way before [#]101986 which introduced `msg` to prevent
good path delayed bugs (which no longer exist) from firing under certain
circumstances when lints were suppressed / silenced
* this is no longer necessary for various reasons I presume
* it shaves off complexity and makes further changes easier to implement
|
|
|
|
|
|
|
|
Simplify `use crate::rustc_foo::bar` occurrences.
They can just be written as `use rustc_foo::bar`, which is far more standard. (I didn't even know that a `crate::` prefix was valid.)
r? ``@eholk``
|
|
They can just be written as `use rustc_foo::bar`, which is far more
standard. (I didn't even know that a `crate::` prefix was valid.)
|
|
rustdoc: dedup search form HTML
This change constructs the search form HTML using JavaScript, instead of plain HTML. It uses a custom element because
- the [parser]'s insert algorithm runs the connected callback synchronously, so we won't get layout jank
- it requires very little HTML, so it's a real win in size
[parser]: https://html.spec.whatwg.org/multipage/parsing.html#create-an-element-for-the-token
This shrinks the standard library by about 60MiB, by my test.
There should be no visible changes. Just use less disk space.
|
|
[rustdoc] Fix bad color for setting cog in ayu theme
Before:
After:
r? ````@notriddle````
|
|
|
|
This change constructs the search form HTML using JavaScript, instead of plain HTML. It uses a custom element because
- the [parser]'s insert algorithm runs the connected callback synchronously, so we won't get layout jank
- it requires very little HTML, so it's a real win in size
[parser]: https://html.spec.whatwg.org/multipage/parsing.html#create-an-element-for-the-token
This shrinks the standard library by about 60MiB, by my test.
|
|
rustdoc-search: search for references
This feature extends rustdoc with syntax and search index information for searching borrow references. Part of https://github.com/rust-lang/rust/issues/60485
## Preview
- [`&mut`](https://notriddle.com/rustdoc-html-demo-11/reference/std/index.html?search=%26mut)
- [`&Option<T> -> Option<&T>`](https://notriddle.com/rustdoc-html-demo-11/reference/std/index.html?search=%26Option%3CT%3E%20-%3E%20Option%3C%26T%3E)
- [`&mut Option<T> -> Option<&mut T>`](https://notriddle.com/rustdoc-html-demo-11/reference/std/index.html?search=%26mut%20Option%3CT%3E%20-%3E%20Option%3C%26mut%20T%3E)
Updated chapter of the book: https://notriddle.com/rustdoc-html-demo-11/reference/rustdoc/read-documentation/search.html
## Motivation
See https://github.com/rust-lang/rust/pull/119676
## Guide-level explanation
You can't search by lifetimes, but other than that it's the same syntax references normally use.
## Reference-level description
<table>
<thead>
<tr>
<th>Shorthand</th>
<th>Explicit names</th>
</tr>
</thead>
<tbody>
<tr><td colspan="2">Before this PR</td></tr>
<tr>
<td><code>[]</code></td>
<td><code>primitive:slice</code> and/or <code>primitive:array</code></td>
</tr>
<tr>
<td><code>[T]</code></td>
<td><code>primitive:slice<T></code> and/or <code>primitive:array<T></code></td>
</tr>
<tr>
<td><code>!</code></td>
<td><code>primitive:never</code></td>
</tr>
<tr>
<td><code>()</code></td>
<td><code>primitive:unit</code> and/or <code>primitive:tuple</code></td>
</tr>
<tr>
<td><code>(T)</code></td>
<td><code>T</code></td>
</tr>
<tr>
<td><code>(T,)</code></td>
<td><code>primitive:tuple<T></code></td>
</tr>
<tr>
<td><code>(T, U -> V, W)</code></td>
<td><code>fn(T, U) -> (V, W)</code>, Fn, FnMut, and FnOnce</td>
</tr>
<tr><td colspan="2">New additions with this PR</td></tr>
<tr>
<td><code>&</code></td>
<td><code>primitive:reference</td>
</tr>
<tr>
<td><code>&mut</code></td>
<td><code>primitive:reference<keyword:mut></td>
</tr>
<tr>
<td><code>&T</code></td>
<td><code>primitive:reference<T></td>
</tr>
<tr>
<td><code>&mut T</code></td>
<td><code>primitive:reference<keyword:mut, T></td>
</tr>
</tbody>
</table>
### Search query grammar
<code><pre><strong>borrow-ref = AMP *WS [MUT] *WS [arg]</strong>
arg = [type-filter *WS COLON *WS] (path [generics] / slice-like / tuple-like / <strong>borrow-ref</strong>)</pre></code>
```
AMP = "&"
MUT = "mut"
```
## Future direction
As described in https://github.com/rust-lang/rust/pull/118194 and https://github.com/rust-lang/rust/pull/119676
* The remaining type expression grammar (this is another step in the type expression grammar: `ReferenceType` is now supported)
* Search subtyping and traits
|
|
|
|
Remove direct dependencies on lazy_static, once_cell and byteorder
The relevant functionality of all three crates is now available and stable in the standard library, i.e. `std::sync::OnceLock` and `{integer}::to_le_bytes`. I think waiting for `LazyLock` (#109736) would give marginally more concise code, but not by much.
|
|
|
|
|
|
|
|
The functionality of all three crates is now available in the standard library.
|
|
|
|
|
|
rustdoc-search: fix description on aliases in results
This needs to start downloading the descriptions after aliases have been added to the result set.
|
|
Always display stability version even if it's the same as the containing item
Fixes https://github.com/rust-lang/rust/issues/118439.
Currently, if the containing item's version is the same as the item's version (like a method), we don't display it on the item.
This was something done on purpose as you can see [here](https://github.com/rust-lang/rust/blob/e9b7bf011478aa8c19ac49afc99853a66ba04319/src/librustdoc/html/render/mod.rs#L949-L955). It was implemented in https://github.com/rust-lang/rust/pull/30686.
I think we should change this because on pages with a lot of items, if someone arrives (through the search or a link) to an item far below the page, they won't know the stability version unless they scroll to the top, which isn't great.
You can see the result [here](https://rustdoc.crud.net/imperio/display-stability-version/std/pin/struct.Pin.html#method.new).
r? `@notriddle`
|
|
This needs to start downloading the descriptions after aliases
have been added to the result set.
|
|
Properly handle emojis as literal prefix in macros
Do not accept the following
```rust
macro_rules! lexes {($($_:tt)*) => {}}
lexes!(🐛"foo");
```
Before, invalid emoji identifiers were gated during parsing instead of lexing in all cases, but this didn't account for macro pre-expansion of literal prefixes.
Fix #123696.
|
|
rustdoc-search: single result for items with multiple paths
Part of #15723
Preview: https://notriddle.com/rustdoc-html-demo-9/reexport-dup/std/index.html?search=hashmap
This change uses the same "exact" paths as trait implementors and type alias inlining to track items with multiple reachable paths. This way, if you search for `vec`, you get only the `std` exports of it, and not the one from `alloc`.
It still includes all the items in the search index so that you can search for them by all available paths. For example, try `core::option` and `std::option`, and notice that the results page doesn't show duplicates, but still shows all the items in their respective crates.
|
|
Simplify `static_assert_size`s.
We want to run them on all 64-bit platforms.
r? `@ghost`
|
|
Fix copy path button
Currently, on all nightly docs, clicking on the "copy path" button triggers a JS error. It's because changes in https://github.com/rust-lang/rust/pull/123706 forgot to update the JS (it contained an image before but not anymore).
I had to make some small changes in the CSS to fix the display when the button was clicked as well.
r? ``@notriddle``
|
|
We want to run them on all 64-bit platforms.
|
|
|
|
Qualifier tweaking
Adding and removing qualifiers in some cases that make things nicer. Details in individual commits.
r? `@compiler-errors`
|
|
Support type '/' to search
Related topic on IRLO: https://internals.rust-lang.org/t/rustdoc-use-key-to-search-instead-of-s/20559
|
|
Because that's the way it should be done.
|
|
In some cases `DUMMY_SP` is already imported. In other cases this commit
adds the necessary import, in files where `DUMMY_SP` is used more than
once.
|
|
|
|
Do not accept the following
```rust
macro_rules! lexes {($($_:tt)*) => {}}
lexes!(🐛"foo");
```
Before, invalid emoji identifiers were gated during parsing instead of lexing in all cases, but this didn't account for macro expansion of literal prefixes.
Fix #123696.
|
|
According to <https://caniuse.com/?search=svg%20favicon>,
SVG favicons are supported in everything but Safari.
When I actually try it in Safari, it's downloading all
three favicons, and nothing looks different when I disable
the 16x16 one.
<https://dev.to/masakudamatsu/favicon-nightmare-how-to-maintain-sanity-3al7>,
which is linked from caniuse above, recommends an ico.
However, the reason they recommend it is the apps that
only support /favicon.ico exactly, and rustdoc can't assume
it will be installed to the site root, so it's unfortunately
up to the webmaster to make sure it's set up.
|
|
This cuts the HTML overhead for a page by about 1KiB,
significantly reducing the overall size of the docs bundle.
|
