Auto merge of rust-lang#124577 - GuillaumeGomez:stabilize-custom_code…

…_classes_in_docs, r=rustdoc

Stabilize `custom_code_classes_in_docs` feature

Fixes rust-lang#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](rust-lang#110800 (comment))).

r? `@notriddle`

compiler/rustc_feature/src/accepted.rs

@@ -138,6 +138,8 @@ declare_features! (
     (accepted, copy_closures, "1.26.0", Some(44490)),
     /// Allows `crate` in paths.
     (accepted, crate_in_paths, "1.30.0", Some(45477)),
+    /// Allows users to provide classes for fenced code block using `class:classname`.
+    (accepted, custom_code_classes_in_docs, "CURRENT_RUSTC_VERSION", Some(79483)),
     /// Allows using `#[debugger_visualizer]` attribute.
     (accepted, debugger_visualizer, "1.71.0", Some(95939)),
     /// Allows rustc to inject a default alloc_error_handler

compiler/rustc_feature/src/unstable.rs

@@ -424,8 +424,6 @@ declare_features! (
     /// Allows function attribute `#[coverage(on/off)]`, to control coverage
     /// instrumentation of that function.
     (unstable, coverage_attribute, "1.74.0", Some(84605)),
-    /// Allows users to provide classes for fenced code block using `class:classname`.
-    (unstable, custom_code_classes_in_docs, "1.74.0", Some(79483)),
     /// Allows non-builtin attributes in inner attribute position.
     (unstable, custom_inner_attributes, "1.30.0", Some(54726)),
     /// Allows custom test frameworks with `#![test_runner]` and `#[test_case]`.

src/doc/rustdoc/src/unstable-features.md

@@ -624,47 +624,3 @@ add the `--scrape-tests` flag.
 
 This flag enables the generation of links in the source code pages which allow the reader
 to jump to a type definition.
-
-### Custom CSS classes for code blocks
-
-```rust
-#![feature(custom_code_classes_in_docs)]
-
-/// ```custom,{class=language-c}
-/// int main(void) { return 0; }
-/// ```
-pub struct Bar;
-```
-
-The text `int main(void) { return 0; }` is rendered without highlighting in a code block
-with the class `language-c`. This can be used to highlight other languages through JavaScript
-libraries for example.
-
-Without the `custom` attribute, it would be generated as a Rust code example with an additional
-`language-C` CSS class. Therefore, if you specifically don't want it to be a Rust code example,
-don't forget to add the `custom` attribute.
-
-To be noted that you can replace `class=` with `.` to achieve the same result:
-
-```rust
-#![feature(custom_code_classes_in_docs)]
-
-/// ```custom,{.language-c}
-/// int main(void) { return 0; }
-/// ```
-pub struct Bar;
-```
-
-To be noted, `rust` and `.rust`/`class=rust` have different effects: `rust` indicates that this is
-a Rust code block whereas the two others add a "rust" CSS class on the code block.
-
-You can also use double quotes:
-
-```rust
-#![feature(custom_code_classes_in_docs)]
-
-/// ```"not rust" {."hello everyone"}
-/// int main(void) { return 0; }
-/// ```
-pub struct Bar;
-```

src/doc/rustdoc/src/write-documentation/documentation-tests.md

@@ -376,6 +376,44 @@ that the code sample should be compiled using the respective edition of Rust.
 # fn foo() {}
 ```
 
+### Custom CSS classes for code blocks
+
+```rust
+/// ```custom,{class=language-c}
+/// int main(void) { return 0; }
+/// ```
+pub struct Bar;
+```
+
+The text `int main(void) { return 0; }` is rendered without highlighting in a code block
+with the class `language-c`. This can be used to highlight other languages through JavaScript
+libraries for example.
+
+Without the `custom` attribute, it would be generated as a Rust code example with an additional
+`language-C` CSS class. Therefore, if you specifically don't want it to be a Rust code example,
+don't forget to add the `custom` attribute.
+
+To be noted that you can replace `class=` with `.` to achieve the same result:
+
+```rust
+/// ```custom,{.language-c}
+/// int main(void) { return 0; }
+/// ```
+pub struct Bar;
+```
+
+To be noted, `rust` and `.rust`/`class=rust` have different effects: `rust` indicates that this is
+a Rust code block whereas the two others add a "rust" CSS class on the code block.
+
+You can also use double quotes:
+
+```rust
+/// ```"not rust" {."hello everyone"}
+/// int main(void) { return 0; }
+/// ```
+pub struct Bar;
+```
+
 ## Syntax reference
 
 The *exact* syntax for code blocks, including the edge cases, can be found

src/librustdoc/doctest.rs

@@ -1343,7 +1343,6 @@ impl<'a, 'hir, 'tcx> HirCollector<'a, 'hir, 'tcx> {
                     def_id.to_def_id(),
                     span_of_fragments(&attrs.doc_strings).unwrap_or(sp),
                 )),
-                self.tcx.features().custom_code_classes_in_docs,
             );
         }
 

src/librustdoc/externalfiles.rs

@@ -46,8 +46,6 @@ impl ExternalHtml {
                 edition,
                 playground,
                 heading_offset: HeadingOffset::H2,
-                // For external files, it'll be disabled until the feature is enabled by default.
-                custom_code_classes_in_docs: false,
             }
             .into_string()
         );
@@ -63,8 +61,6 @@ impl ExternalHtml {
                 edition,
                 playground,
                 heading_offset: HeadingOffset::H2,
-                // For external files, it'll be disabled until the feature is enabled by default.
-                custom_code_classes_in_docs: false,
             }
             .into_string()
         );