Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

librustdoc: Use correct heading levels. #89506

Merged
merged 8 commits into from
Oct 6, 2021
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0001.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.
GuillaumeGomez marked this conversation as resolved.
Show resolved Hide resolved

This error suggests that the expression arm corresponding to the noted pattern
will never be reached as for all possible values of the expression being
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0002.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error indicates that an empty match expression is invalid because the type
it is matching on is non-empty (there exist values of this type). In safe code
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0007.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error indicates that the bindings in a match arm would require a value to
be moved into more than one location, thus violating unique ownership. Code
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0009.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

In a pattern, all values that don't implement the `Copy` trait have to be bound
the same way. The goal here is to avoid binding simultaneously by-move and
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0014.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Constants can only be initialized by a constant value or, in a future
version of Rust, a call to a const function. This error indicates the use
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0073.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

You cannot define a struct (or enum) `Foo` that requires an instance of `Foo`
in order to make a new `Foo` value. This is because there would be no way a
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0074.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

When using the `#[simd]` attribute on a tuple struct, the components of the
tuple struct must all be of a concrete, nongeneric type so the compiler can
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0087.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Too many type arguments were supplied for a function. For example:

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0088.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

You gave too many lifetime arguments. Erroneous code example:

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0089.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Too few type arguments were supplied for a function. For example:

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0090.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

You gave too few lifetime arguments. Example:

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0110.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

You tried to provide a lifetime to a type which doesn't need it.
See `E0109` for more details.
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0136.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

More than one `main` function was found.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0137.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

More than one function was declared with the `#[main]` attribute.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0139.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

There are various restrictions on transmuting between types in Rust; for example
types being transmuted must have the same size. To apply all these restrictions,
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0154.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Imports (`use` statements) are not allowed after non-item statements, such as
variable declarations and expression statements.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0162.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

An `if let` pattern attempts to match the pattern, and enters the body if the
match was successful. If the match is irrefutable (when it cannot fail to
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0165.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

A `while let` pattern attempts to match the pattern, and enters the body if the
match was successful. If the match is irrefutable (when it cannot fail to
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0193.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

`where` clauses must use generic type parameters: it does not make sense to use
them otherwise. An example causing this error:
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0205.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

An attempt to implement the `Copy` trait for an enum failed because one of the
variants does not implement `Copy`. To fix this, you must implement `Copy` for
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0211.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

You used a function or type which doesn't fit the requirements for where it was
used. Erroneous code examples:
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0243.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error indicates that not enough type parameters were found in a type or
trait.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0244.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error indicates that too many type parameters were found in a type or
trait.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0251.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Two items of the same name cannot be imported without rebinding one of the
items under a new local name.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0256.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

You can't import a type or module when the name of the item being imported is
the same as another type or submodule defined in the module.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0281.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

You tried to supply a type which doesn't implement some trait in a location
which expected that trait. This error typically occurs when working with
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0297.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Patterns used to bind names must be irrefutable. That is, they must guarantee
that a name will be extracted in all cases. Instead of pattern matching the
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0301.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Mutable borrows are not allowed in pattern guards, because matching cannot have
side effects. Side effects could alter the matched object or the environment
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0302.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Assignments are not allowed in pattern guards, because matching cannot have
side effects. Side effects could alter the matched object or the environment
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0303.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Sub-bindings, e.g. `ref x @ Some(ref y)` are now allowed under
`#![feature(bindings_after_at)]` and checked to make sure that
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0329.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

An attempt was made to access an associated constant through either a generic
type parameter or `Self`. This is not supported yet. An example causing this
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0383.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error occurs when an attempt is made to partially reinitialize a
structure that is currently uninitialized.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0386.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error occurs when an attempt is made to mutate the target of a mutable
reference stored inside an immutable container.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0387.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error occurs when an attempt is made to mutate or mutably reference data
that a closure has captured immutably.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0388.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0389.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

An attempt was made to mutate data using a non-mutable reference. This
commonly occurs when attempting to assign to a non-mutable reference of a
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0398.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

In Rust 1.3, the default object lifetime bounds are expected to change, as
described in [RFC 1156]. You are getting a warning because the compiler
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0399.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler
### Note: this error code is no longer emitted by the compiler

You implemented a trait, overriding one or more of its associated types but did
not reimplement its default methods.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0439.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

The length of the platform-intrinsic function `simd_shuffle` wasn't specified.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0447.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

The `pub` keyword was used inside a function.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0448.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

The `pub` keyword was used inside a public enum.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0497.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

A stability attribute was used outside of the standard library.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0504.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

This error occurs when an attempt is made to move a borrowed variable into a
closure.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0595.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Closures cannot mutate immutable captured variables.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0619.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

The type-checker needed to know the type of an expression, but that type had not
yet been inferred.
Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0633.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

The `unwind` attribute was malformed.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0665.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

The `Default` trait was derived on an enum.

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_error_codes/src/error_codes/E0671.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#### Note: this error code is no longer emitted by the compiler.
### Note: this error code is no longer emitted by the compiler.

Const parameters cannot depend on type parameters.
The following is therefore invalid:
Expand Down
4 changes: 2 additions & 2 deletions src/librustdoc/externalfiles.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,14 +39,14 @@ impl ExternalHtml {
let bc = format!(
"{}{}",
bc,
Markdown(&m_bc, &[], id_map, codes, edition, playground).into_string()
Markdown(&m_bc, &[], id_map, codes, edition, playground, 0).into_string()
);
let ac = load_external_files(after_content, diag)?;
let m_ac = load_external_files(md_after_content, diag)?;
let ac = format!(
"{}{}",
ac,
Markdown(&m_ac, &[], id_map, codes, edition, playground).into_string()
Markdown(&m_ac, &[], id_map, codes, edition, playground, 0).into_string()
);
Some(ExternalHtml { in_header: ih, before_content: bc, after_content: ac })
}
Expand Down
21 changes: 13 additions & 8 deletions src/librustdoc/html/markdown.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
//!
//! let s = "My *markdown* _text_";
//! let mut id_map = IdMap::new();
//! let md = Markdown(s, &[], &mut id_map, ErrorCodes::Yes, Edition::Edition2015, &None);
//! let md = Markdown(s, &[], &mut id_map, ErrorCodes::Yes, Edition::Edition2015, &None, 0);
//! let html = md.into_string();
//! // ... something using html
//! ```
Expand Down Expand Up @@ -47,6 +47,8 @@ use pulldown_cmark::{
#[cfg(test)]
mod tests;

const MAX_HEADER_LEVEL: u32 = 6;

/// Options for rendering Markdown in the main body of documentation.
pub(crate) fn main_body_opts() -> Options {
Options::ENABLE_TABLES
Expand Down Expand Up @@ -78,6 +80,7 @@ pub struct Markdown<'a>(
/// Default edition to use when parsing doctests (to add a `fn main`).
pub Edition,
pub &'a Option<Playground>,
pub u32,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a doc comment explaining what this field is. Out of context, it's impossible to know what it is without going through the code.

GuillaumeGomez marked this conversation as resolved.
Show resolved Hide resolved
);
/// A tuple struct like `Markdown` that renders the markdown with a table of contents.
crate struct MarkdownWithToc<'a>(
Expand Down Expand Up @@ -489,11 +492,12 @@ struct HeadingLinks<'a, 'b, 'ids, I> {
toc: Option<&'b mut TocBuilder>,
buf: VecDeque<SpannedEvent<'a>>,
id_map: &'ids mut IdMap,
level: u32,
GuillaumeGomez marked this conversation as resolved.
Show resolved Hide resolved
}

impl<'a, 'b, 'ids, I> HeadingLinks<'a, 'b, 'ids, I> {
fn new(iter: I, toc: Option<&'b mut TocBuilder>, ids: &'ids mut IdMap) -> Self {
HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids }
fn new(iter: I, toc: Option<&'b mut TocBuilder>, ids: &'ids mut IdMap, level: u32) -> Self {
GuillaumeGomez marked this conversation as resolved.
Show resolved Hide resolved
HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids, level }
}
}

Expand Down Expand Up @@ -530,6 +534,7 @@ impl<'a, 'b, 'ids, I: Iterator<Item = SpannedEvent<'a>>> Iterator
self.buf.push_front((Event::Html(format!("{} ", sec).into()), 0..0));
}

let level = std::cmp::min(level + self.level + 1, MAX_HEADER_LEVEL);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When level = 0, you get # My Header ➡️ <h2>My Header</h2>. This seems weird to me.

I would have expected that HeadingLinks { level: 0 } would mean that headings aren't getting modified. Instead, you've made it so that there is no way to tell HeadingLinks to not bump the levels. It's also silently changing how the standalone markdown files (stuff like /src/doc/index.md) are generated, and it's why the error index got changed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Completely forgot about the standalone markdown files, this is an excellent point!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When level = 0, you get # My Header ➡️ <h2>My Header</h2>. This seems weird to me.

I wasn't feeling great about it either but since I'm not the only thinking this, we should definitely make the heading level match the level we use.

Copy link
Contributor Author

@yaymukund yaymukund Oct 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to be clear - you want markdown in the error index to behave differently (# this is an h1) from doc comments in std (# this is an h2)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why it makes sense to talk about them "behaving the same" as doc comments. They're totally different.

For one thing, the biggest reason why this probably has to be fixed by changing rustdoc's behavior is that there's no way for the end-user to know what the right heading level is. The same exact doc comment might be rendered at multiple levels in multiple pages, like slice::first on the slice page (which is a fourth-level header, so the items in the doc comment should be h5), and slice::first on Vec (which is an h3, so its doc comment headers should start at h4).

For the error index, you're probably in the right here. The error index pages each have h1's at the beginning, and when they're viewed as individual documents, this works (they're .md files, so you expect them to be viewed using things like GitHub's markdown preview pane, or inside an IDE). But when they're combined to form the full error index, the resulting page has multiple h1's.

But for standalone markdown files, this seems like a breaking change made with insufficient motivation. Those aren't being combined to form huge mega-documents, and it's a stable feature, not just some internal thing used by the compiler, so changing its behavior should only be done with very compelling reasons.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The short version: yes to changing doc comments, yes to changing the error index, no to changing standalone markdown files.

Copy link
Contributor Author

@yaymukund yaymukund Oct 4, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great - this is very helpful context, thanks for explaining. I agree with you. I'll update the code + maybe add a test for this standalone markdown feature if I can figure out how to do that.

self.buf.push_back((Event::Html(format!("</a></h{}>", level).into()), 0..0));

let start_tags = format!(
Expand Down Expand Up @@ -1005,7 +1010,7 @@ impl LangString {

impl Markdown<'_> {
pub fn into_string(self) -> String {
let Markdown(md, links, mut ids, codes, edition, playground) = self;
let Markdown(md, links, mut ids, codes, edition, playground, level) = self;
GuillaumeGomez marked this conversation as resolved.
Show resolved Hide resolved

// This is actually common enough to special-case
if md.is_empty() {
Expand All @@ -1026,7 +1031,7 @@ impl Markdown<'_> {

let mut s = String::with_capacity(md.len() * 3 / 2);

let p = HeadingLinks::new(p, None, &mut ids);
let p = HeadingLinks::new(p, None, &mut ids, level);
let p = Footnotes::new(p);
let p = LinkReplacer::new(p.map(|(ev, _)| ev), links);
let p = TableWrapper::new(p);
Expand All @@ -1048,7 +1053,7 @@ impl MarkdownWithToc<'_> {
let mut toc = TocBuilder::new();

{
let p = HeadingLinks::new(p, Some(&mut toc), &mut ids);
let p = HeadingLinks::new(p, Some(&mut toc), &mut ids, 0);
let p = Footnotes::new(p);
let p = TableWrapper::new(p.map(|(ev, _)| ev));
let p = CodeBlocks::new(p, codes, edition, playground);
Expand Down Expand Up @@ -1077,7 +1082,7 @@ impl MarkdownHtml<'_> {

let mut s = String::with_capacity(md.len() * 3 / 2);

let p = HeadingLinks::new(p, None, &mut ids);
let p = HeadingLinks::new(p, None, &mut ids, 0);
let p = Footnotes::new(p);
let p = TableWrapper::new(p.map(|(ev, _)| ev));
let p = CodeBlocks::new(p, codes, edition, playground);
Expand Down Expand Up @@ -1295,7 +1300,7 @@ crate fn markdown_links(md: &str) -> Vec<MarkdownLink> {
// There's no need to thread an IdMap through to here because
// the IDs generated aren't going to be emitted anywhere.
let mut ids = IdMap::new();
let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids));
let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids, 0));

for ev in iter {
if let Event::Start(Tag::Link(kind, dest, _)) = ev.0 {
Expand Down
Loading