| Age | Commit message (Collapse) | Author | Lines |
|---|
|
Include trailing commas in wrapped function declarations [RustDoc]
Fixes #125901.
|
|
|
|
|
|
|
|
|
|
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
|
|
call
|
|
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
|
|
[perf] Delay the construction of early lint diag structs
Attacks some of the perf regressions from https://github.com/rust-lang/rust/pull/124417#issuecomment-2123700666.
See individual commits for details. The first three commits are not strictly necessary.
However, the 2nd one (06bc4fc67145e3a7be9b5a2cf2b5968cef36e587, *Remove `LintDiagnostic::msg`*) makes the main change way nicer to implement.
It's also pretty sweet on its own if I may say so myself.
|
|
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
|
|
|
|
Rename Unsafe to Safety
Alternative to #124455, which is to just have one Safety enum to use everywhere, this opens the posibility of adding `ast::Safety::Safe` that's useful for unsafe extern blocks.
This leaves us today with:
```rust
enum ast::Safety {
Unsafe(Span),
Default,
// Safe (going to be added for unsafe extern blocks)
}
enum hir::Safety {
Unsafe,
Safe,
}
```
We would convert from `ast::Safety::Default` into the right Safety level according the context.
|
|
Improve parser
Fixes #124935.
- Add a few more help diagnostics to incorrect semicolons
- Overall improved that function
- Addded a few comments
- Renamed diff_marker fns to git_diff_marker
|
|
Add `-` (stdin) support in rustdoc
This PR adds support for the special `-` input which threats the input as coming from *stdin* instead of being a filepath.
Doing this also makes `rustdoc` consistent with `rustc` and ~~every~~ other tools. Full [motivation](https://github.com/rust-lang/rust/pull/124611#issuecomment-2094234876).
Fixes https://github.com/rust-lang/rust/issues/123671
r? `@fmease`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
r=GuillaumeGomez
Always hide private fields in aliased type
This PR adds a new rustdoc pass that unconditionally always strips all private fields in aliased type, since showing them, even with `--document-private-items`, is confusing, unhelpful, and run backwards to the "Aliased type" feature, which is to show the type as it would be seen by the user.
r? ```@GuillaumeGomez```
Fixes #124938
Fixes #123860
|
|
|
|
|
|
|
|
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.)
|
|
To decide if internal items should be inlined in a doc page,
check if the crate is itself internal, rather than if it has
the rustc_private feature flag. The standard library uses
internal items, but is not itself internal and should not show
internal items on its docs pages.
|
|
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
|
|
|
|
|
|
Some hir cleanups
It seemed odd to not put `AnonConst` in the arena, compared with the other types that we did put into an arena. This way we can also give it a `Span` without growing a lot of other HIR data structures because of the extra field.
r? compiler
|
|
|
|
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.
|
|
|
|
Fix some typos in comments
|
|
Signed-off-by: TechVest <techdashen@qq.com>
|
