profile
viewpoint

pull request commentrust-lang/rust

Overload `Iterator::last()` for `IntoIter`.

As I mentioned in https://github.com/rust-lang/rust/pull/76087#discussion_r479784179 all last needs to do is call self.next_back().

hbina

comment created time in 4 days

pull request commentrust-lang/rust

Update Option Documentation

The broken link was already fixed by #77971 so it works in the nightly docs.

gsquire

comment created time in 10 days

issue closedrust-lang/rust

rustdoc: Search returns weird and unhelpful results

I found this while searching for Vec::sort:

image

This is an issue on nightly, beta, and stable.

closed time in 10 days

camelid

issue commentrust-lang/rust

rustdoc: Search returns weird and unhelpful results

Duplicate of #63080

camelid

comment created time in 10 days

Pull request review commentrust-lang/rust

Use double quote for rustdoc html

 themePicker.onblur = handleThemeButtonsBlur;     // with rustdoc running in parallel.     all_indexes.sort();     {-        let mut v = String::from("var searchIndex = JSON.parse('{\\\n");+        let mut v = String::from("var searchIndex = JSON.parse(\"{\\n");         v.push_str(&all_indexes.join(",\\\n"));         // "addSearchOptions" has to be called first so the crate filtering can be set before the         // search might start (if it's set into the URL for example).-        v.push_str("\\\n}');\naddSearchOptions(searchIndex);initSearch(searchIndex);");+        v.push_str("\\\n}\");\naddSearchOptions(searchIndex);initSearch(searchIndex);");
        v.push_str("\\\n}');\naddSearchOptions(searchIndex);initSearch(searchIndex);");

Again, this needs to stay using a single quote for now.

pickfire

comment created time in 10 days

Pull request review commentrust-lang/rust

Use double quote for rustdoc html

 themePicker.onblur = handleThemeButtonsBlur;     // with rustdoc running in parallel.     all_indexes.sort();     {-        let mut v = String::from("var searchIndex = JSON.parse('{\\\n");+        let mut v = String::from("var searchIndex = JSON.parse(\"{\\n");
        let mut v = String::from("var searchIndex = JSON.parse('{\\\n");

This needs to stay using single quotes because the strings being inserted here don't currently have the double quotes escaped. Also this was removing a backslash that I can only assume was a typo.

This is the cause of the CI failure.

pickfire

comment created time in 10 days

Pull request review commentrust-lang/rust

Use double quote for rustdoc html

 function handleThemeButtonsBlur(e) {{ themePicker.onclick = switchThemeButtonState; themePicker.onblur = handleThemeButtonsBlur; {}.forEach(function(item) {{-    var but = document.createElement('button');+    var but = document.createElement(\"button\");
    var but = document.createElement("button");

This is inside a raw string.

pickfire

comment created time in 10 days

PullRequestReviewEvent
PullRequestReviewEvent

Pull request review commentrust-lang/rust

Add automatic_links lint

 warning: unclosed HTML tag `h1`  warning: 2 warnings emitted ```++## automatic_links++This lint is **nightly-only** and **warns by default**. It detects links which+could use the "automatic" link syntax. For example:++```rust+/// http://hello.rs+/// [http://a.com](http://a.com)+/// [http://b.com]+///+/// [http://b.com]: http://b.com

You need to use domains like example.com in documentation not just random domains. See https://en.wikipedia.org/wiki/Example.com.

GuillaumeGomez

comment created time in 10 days

PullRequestReviewEvent

pull request commentrust-lang/rust

Add automatic_links lint

This lint's name doesn't make much sense. It doesn't detect automatic links. See the lint naming guidelines, specifically: "Lint names should state the bad thing being checked for"

It has false positives, for example:

//! ```text
//! https://example.com/
//! ```

warns but shouldn't because you can't put links inside code blocks.

As this is nightly only it will need a tracking issue, so either #77501 should remain open or a new issue needs to be created.

GuillaumeGomez

comment created time in 10 days

pull request commentrust-lang/rust

Remove compiler-synthesized reexports when documenting

@bors r+

GuillaumeGomez

comment created time in 10 days

issue commentrust-lang/rust

the trait `core::default::Default` is not implemented for `*mut core::ffi::c_void`

This has been requested before: #43722

lygstate

comment created time in 14 days

pull request commentrust-lang/rust

Show summary lines on cross-crate re-exports

Looks good.

@bors r+ p=1

jyn514

comment created time in 15 days

Pull request review commentrust-lang/rust

Show summary lines on cross-crate re-exports

 fn merge_attrs(     // doc comments show up before the original doc comments     // when we render them.     if let Some(inner) = new_attrs {-        if let Some(new_id) = parent_module {-            let diag = cx.sess().diagnostic();-            Attributes::from_ast(diag, old_attrs, Some((inner, new_id)))-        } else {-            let mut both = inner.to_vec();-            both.extend_from_slice(old_attrs);-            both.clean(cx)+        if !inner.is_empty() {

inner includes all attributes on the pub use statement not just doc comments. This means the std docs aren't fixed by this because all pub use statements have at least a stability attribute.

jyn514

comment created time in 15 days

PullRequestReviewEvent

issue commentrust-lang/rust

Missing short summaries for reexported items in rustdoc

This was added to distinguish between the attributes on the original item and attributes on the re-export: 8fbfdc5.

Right, I figured that's what it was trying to do but the Divider is being placed at the beginning of the list of DocFragments: https://github.com/rust-lang/rust/blob/c71248b70870960af9993de4f31d3cba9bbce7e8/src/librustdoc/clean/types.rs#L614 so it's not actually dividing anything. The result is that collapse_docs is still collapsing the docs as it did before so if a reexport has extra docs, all links are resolved relative to the local crate.

Rather than adding Divider couldn't collapse_docs check for differing parent_modules to decide whether to merge DocFragments? That seems like the simpler solution.

ollie27

comment created time in 15 days

issue closedrust-lang/rust

Rustdoc: Trait implementations for Debug, Copy, Clone etc. link to nightly/core, even on stable

When generating documentation for a type that implements Debug, Copy, Clone etc., the links regarding those traits in the Trait Implementations section link to, e.g., https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html.

I expected them to link to https://doc.rust-lang.org/std/fmt/trait.Debug.html etc.

To reproduce: rustdoc test.rs, where test.rs contains the following

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Foo(u8);

// It's not dependant on it being derived, either
pub struct Bar(u8);

impl Clone for Bar {
    fn clone(&self) -> Bar {
        Bar(self.0)
    }
}

<details> <summary>Meta</summary>

rustdoc --version --verbose:

rustdoc 1.16.0 (30cf806ef 2017-03-10) binary: rustdoc commit-hash: 30cf806ef8881c41821fbd43e5cf3699c5290c16 commit-date: 2017-03-10 host: x86_64-pc-windows-gnu release: 1.16.0 LLVM version: 3.9 </details>

closed time in 17 days

chordowl

issue commentrust-lang/rust

Missing short summaries for reexported items in rustdoc

Testing locally, this is fixed by simply removing the newly added DocFragmentKind::Divider but I don't know what that was added for so I don't know if that's the correct fix.

ollie27

comment created time in 17 days

issue openedrust-lang/rust

Missing short summaries for reexported items in rustdoc

For example the current nightly docs show: image

The summary lines for the reexported modules is missing. They're also missing from the search index and sidebar.

This is a regression from #77519. cc @jyn514 @GuillaumeGomez

created time in 17 days

PullRequestReviewEvent
PullRequestReviewEvent

Pull request review commentrust-lang/rust

Avoid SeqCst or static mut in mach_timebase_info and QueryPerformanceFrequency caches

 mod perf_counter {     }      fn frequency() -> c::LARGE_INTEGER {-        static mut FREQUENCY: c::LARGE_INTEGER = 0;-        static STATE: AtomicUsize = AtomicUsize::new(0);-+        // Either the cached result of `QueryPerformanceFrequency` or `0` for+        // uninitialized. Storing this as a single `AtomicU64` allows us to use+        // `Relaxed` operations, as we are only interested in the effects on a+        // single memory location.+        static FREQUENCY: AtomicU64 = AtomicU64::new(0);

How about using AtomicI64 to avoid casting between u64 and c::LARGE_INTEGER?

thomcc

comment created time in 17 days

issue closedrust-lang/rust

Rustdoc question mark next to search not visible in dark theme

The new question mark that was added next to the search box with 1.47 does not change its color when switching to the dark theme. The colors are so similar that the button just appears as a white box unless you look really close.

image

closed time in 17 days

Nashenas88

issue commentrust-lang/rust

Rustdoc question mark next to search not visible in dark theme

This was fixed by #75837 which I guess should have been backported. Either way this is fixed in 1.48.

Nashenas88

comment created time in 17 days

issue commentrust-lang/rust

Add a blanket impl for `core::fmt::Write` if there is an impl for `std::io::Write`

An adapter struct might be the way to solve this. There is even a struct already in std that could maybe be made public: https://github.com/rust-lang/rust/blob/5ddef544fa26c5535376fa424baf30cb985f7cb1/library/std/src/io/mod.rs#L1496-L1501

camelid

comment created time in 17 days

pull request commentrust-lang/rust

Allow ascii whitespace char for doc aliases

The issue I had with whitespace is that search queries are trimmed so if an alias begins with or ends in whitespace then it's impossible to search for it. We could allow spaces as long as they're not at the beginning or end of the alias though.

GuillaumeGomez

comment created time in 21 days

pull request commentrust-lang/rust

Add missing_docs lint to the rustdoc lint group

The lint is emitted by rustdoc too. :)

Yes, but it's also emitted by rustc and the rustdoc lint group is for lints only emitted by rustdoc. From #56689:

I deliberately didn't include missing_docs because this is kind of a stepping stone for moving our lints into tool lints (i.e. #![warn(rustdoc::private_doc_tests)]), since all of these are specifically emitted by rustdoc.

My main question is what would the rustdoc lint group be for if missing_docs is added?

GuillaumeGomez

comment created time in 21 days

pull request commentrust-lang/rust

Unclosed html tag lint

I'm strongly against adding really precise heuristics for catching broken HTML, we'd need a markdown-compatible HTML parser with recovery and that would be a mess for very marginal gain.

Hmm, I agree that we don't want this code to get too complicated. So yeah, maybe just catching some common cases might be the best we should do. Ideally we could actually fix close the unclosed tags so the rendering of the rest of the page isn't completely broken but that might be getting way too complicated.

I do think #67799 should to be left open at least until this lint is stabilized and warn by default though. At the very least we need a tracking issue for doing that and reusing #67799 seems like the easiest choice.

GuillaumeGomez

comment created time in 21 days

Pull request review commentrust-lang/rust

Unclosed html tag lint

 fn extract_tag( ) {     let mut iter = text.chars().enumerate().peekable(); -    while let Some((start_pos, c)) = iter.next() {+    'top: while let Some((start_pos, c)) = iter.next() {         if c == '<' {             let mut tag_name = String::new();             let mut is_closing = false;-            while let Some((pos, c)) = iter.peek() {+            let mut prev_pos = start_pos;+            loop {+                let (pos, c) = match iter.peek() {+                    Some((pos, c)) => (*pos, *c),+                    // In case we reached the of the doc comment, we want to check that it's an+                    // unclosed HTML tag. For example "/// <h3".+                    None => (prev_pos, '\0'),+                };+                prev_pos = pos;                 // Checking if this is a closing tag (like `</a>` for `<a>`).-                if *c == '/' && tag_name.is_empty() {+                if c == '/' && tag_name.is_empty() {                     is_closing = true;-                } else if c.is_ascii_alphanumeric() && !c.is_ascii_uppercase() {-                    tag_name.push(*c);+                } else if c.is_ascii_alphanumeric() {+                    tag_name.push(c);

I don't see what problems that could cause but if the original case needs to be preserved in tags then you should use eq_ignore_ascii_case to compare strings. .to_lowercase() allocates a new String which is very inefficient.

GuillaumeGomez

comment created time in 21 days

PullRequestReviewEvent

Pull request review commentrust-lang/rust

Revamp rustdoc docs about documentation using `cfg`

 pub struct UnixToken; Here, the respective tokens can only be used by dependent crates on their respective platforms, but they will both appear in documentation. +### Interactions between platform-specific docs++Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each+platform (such a magic wand has been called the ['holy grail of rustdoc'][#1998]). Instead,+it sees *all* of your code at once, the same way the Rust compiler would if you passed it+`--cfg doc`. However, Rustdoc has a trick up its sleeve to handle platform-specific code if it+*does* receive it.++To document your crate, Rustdoc only needs to know the public signature of your functions.+In particular, it doesn't have know how any of your functions are implemented, so it ignores
In particular, it doesn't have to know how any of your functions are implemented, so it ignores
jyn514

comment created time in 21 days

PullRequestReviewEvent
PullRequestReviewEvent

Pull request review commentrust-lang/rust

Reexported item lints

 impl Clean<Vec<Item>> for doctree::ExternCrate<'_> {  impl Clean<Vec<Item>> for doctree::Import<'_> {     fn clean(&self, cx: &DocContext<'_>) -> Vec<Item> {+        // We need this comparison because some imports (for std types for example)+        // are "inserted" as well but directly by the compiler and they should not be+        // taken into account.+        if self.span.is_dummy() {+            return Vec::new();+        }

The only ImportItems this PR is adding are ones the have been inlined. The prelude imports are private and so are never inlined so this PR is not adding new ImportItems for them.

There is actually a visible change from this. Currently, if you build docs with --no-defaults then use std::prelude::v1::*; shows up in the Re-exports section in the crate root. This change removes that line. That's something that could be tested assuming hiding that line is intentional. extern crate std; also shows up, should that also be hidden?

Again, please could you move this change to a different PR.

GuillaumeGomez

comment created time in 22 days

PullRequestReviewEvent

Pull request review commentrust-lang/rust

Reexported item lints

 impl Clean<Vec<Item>> for doctree::ExternCrate<'_> {  impl Clean<Vec<Item>> for doctree::Import<'_> {     fn clean(&self, cx: &DocContext<'_>) -> Vec<Item> {+        // We need this comparison because some imports (for std types for example)+        // are "inserted" as well but directly by the compiler and they should not be+        // taken into account.+        if self.span.is_dummy() {+            return Vec::new();+        }

Okay, I agree that rustdoc should ignore imports automatically added by rustc. However, that doesn't seem to have anything to do with the rest of this PR so it should be moved to a separate one although this could just be done if/when a lint is added that would actually need this.

GuillaumeGomez

comment created time in 22 days

PullRequestReviewEvent

Pull request review commentrust-lang/rust

Unclosed html tag lint

 fn extract_tag( ) {     let mut iter = text.chars().enumerate().peekable(); -    while let Some((start_pos, c)) = iter.next() {+    'top: while let Some((start_pos, c)) = iter.next() {         if c == '<' {             let mut tag_name = String::new();             let mut is_closing = false;-            while let Some((pos, c)) = iter.peek() {+            let mut prev_pos = start_pos;+            loop {+                let (pos, c) = match iter.peek() {+                    Some((pos, c)) => (*pos, *c),+                    // In case we reached the of the doc comment, we want to check that it's an+                    // unclosed HTML tag. For example "/// <h3".+                    None => (prev_pos, '\0'),+                };+                prev_pos = pos;                 // Checking if this is a closing tag (like `</a>` for `<a>`).-                if *c == '/' && tag_name.is_empty() {+                if c == '/' && tag_name.is_empty() {                     is_closing = true;-                } else if c.is_ascii_alphanumeric() && !c.is_ascii_uppercase() {-                    tag_name.push(*c);+                } else if c.is_ascii_alphanumeric() {+                    tag_name.push(c);
                    tag_name.push(c.to_ascii_lowercase());

This way all of the .to_lowercase() calls elsewhere can be removed.

GuillaumeGomez

comment created time in 24 days

Pull request review commentrust-lang/rust

Unclosed html tag lint

+use super::{span_of_attrs, Pass};+use crate::clean::*;+use crate::core::DocContext;+use crate::fold::DocFolder;+use crate::html::markdown::opts;+use core::ops::Range;+use pulldown_cmark::{Event, Parser};+use rustc_feature::UnstableFeatures;+use rustc_session::lint;++pub const CHECK_INVALID_HTML_TAGS: Pass = Pass {+    name: "check-invalid-html-tags",+    run: check_invalid_html_tags,+    description: "detects invalid HTML tags in doc comments",+};++struct InvalidHtmlTagsLinter<'a, 'tcx> {+    cx: &'a DocContext<'tcx>,+}++impl<'a, 'tcx> InvalidHtmlTagsLinter<'a, 'tcx> {+    fn new(cx: &'a DocContext<'tcx>) -> Self {+        InvalidHtmlTagsLinter { cx }+    }+}++pub fn check_invalid_html_tags(krate: Crate, cx: &DocContext<'_>) -> Crate {+    if !UnstableFeatures::from_environment().is_nightly_build() {+        krate+    } else {+        let mut coll = InvalidHtmlTagsLinter::new(cx);++        coll.fold_crate(krate)+    }+}++const ALLOWED_UNCLOSED: &[&str] = &[+    "area", "base", "br", "col", "embed", "hr", "img", "input", "keygen", "link", "meta", "param",+    "source", "track", "wbr",+];++fn drop_tag(+    tags: &mut Vec<(String, Range<usize>)>,+    tag_name: String,+    range: Range<usize>,+    f: &impl Fn(&str, &Range<usize>),+) {+    let tag_name_low = tag_name.to_lowercase();+    if let Some(pos) = tags.iter().rev().position(|(t, _)| t.to_lowercase() == tag_name_low) {+        // Because this is from a `rev` iterator, the position is reversed as well!+        let pos = tags.len() - 1 - pos;+        // If the tag is nested inside a "<script>" or a "<style>" tag, no warning should+        // be emitted.+        let should_not_warn = tags.iter().take(pos + 1).any(|(at, _)| {+            let at = at.to_lowercase();+            at == "script" || at == "style"+        });+        for (last_tag_name, last_tag_span) in tags.drain(pos + 1..) {+            if should_not_warn {+                continue;+            }+            let last_tag_name_low = last_tag_name.to_lowercase();+            if ALLOWED_UNCLOSED.iter().any(|&at| at == &last_tag_name_low) {+                continue;+            }+            // `tags` is used as a queue, meaning that everything after `pos` is included inside it.+            // So `<h2><h3></h2>` will look like `["h2", "h3"]`. So when closing `h2`, we will still+            // have `h3`, meaning the tag wasn't closed as it should have.+            f(&format!("unclosed HTML tag `{}`", last_tag_name), &last_tag_span);+        }+        // Remove the `tag_name` that was originally closed+        tags.pop();+    } else {+        // It can happen for example in this case: `<h2></script></h2>` (the `h2` tag isn't required+        // but it helps for the visualization).+        f(&format!("unopened HTML tag `{}`", tag_name), &range);+    }+}++fn extract_tag(+    tags: &mut Vec<(String, Range<usize>)>,+    text: &str,+    range: Range<usize>,+    f: &impl Fn(&str, &Range<usize>),+) {+    let mut iter = text.chars().enumerate().peekable();
    let mut iter = text.char_indices().peekable();

This is what will actually fix the ICE with none ASCII characters. The two for _ in 0..c.len_utf8() { loops below aren't correct because they're confusing bytes and characters.

GuillaumeGomez

comment created time in 24 days

Pull request review commentrust-lang/rust

Unclosed html tag lint

 fn drop_tag(     range: Range<usize>,     f: &impl Fn(&str, &Range<usize>), ) {-    if let Some(pos) = tags.iter().rev().position(|(t, _)| *t == tag_name) {+    let tag_name_low = tag_name.to_lowercase();+    if let Some(pos) = tags.iter().rev().position(|(t, _)| t.to_lowercase() == tag_name_low) {         // Because this is from a `rev` iterator, the position is reversed as well!

How about using rposition?

GuillaumeGomez

comment created time in 24 days

Pull request review commentrust-lang/rust

Unclosed html tag lint

+#![allow(invalid_html_tags)]

invalid_html_tags is allow by default.

GuillaumeGomez

comment created time in 24 days

PullRequestReviewEvent
PullRequestReviewEvent

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

  // ignore-tidy-linelength -// Crate-level is accepted, though it is almost certainly unused?+#![deny(unused_attributes)]+//~^ NOTE not a function or static+//~^^ NOTE the lint level is defined here+//~^^^ NOTE not an `extern crate` item+//~^^^^ NOTE not a function or static+//~^^^^^ NOTE not a function or closure++#![macro_export]+#![main]+#![start]+#![repr()]+#![path = "3800"]+#![automatically_derived]

I don't see them in the the stderr file. I'm talking specifically about these:

#![macro_export]
#![main]
#![start]
#![repr()]
#![path = "3800"]
#![automatically_derived]

The notes attached to the #[deny()] attribute are just the notes that are applied to the crate span which I was refering to in https://github.com/rust-lang/rust/pull/76329/files#r499083161.

GuillaumeGomez

comment created time in 24 days

PullRequestReviewEvent

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

  // ignore-tidy-linelength -// Crate-level is accepted, though it is almost certainly unused?+#![deny(unused_attributes)]+//~^ NOTE not a function or static+//~^^ NOTE the lint level is defined here+//~^^^ NOTE not an `extern crate` item+//~^^^^ NOTE not a function or static+//~^^^^^ NOTE not a function or closure++#![macro_export]+#![main]+#![start]+#![repr()]+#![path = "3800"]+#![automatically_derived]

Where are the warnings or errors from these attributes? They were triggering unused_attributes and if they're not anymore then that's a regression.

GuillaumeGomez

comment created time in 24 days

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

  // ignore-tidy-linelength -// Crate-level is accepted, though it is almost certainly unused?+#![deny(unused_attributes)]

This shouldn't have been added. If attributes are only triggering the unused_attributes lint then they should stay in issue-43106-gating-of-builtin-attrs.rs.

GuillaumeGomez

comment created time in 24 days

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

 LL | | LL | | }    | |_- not a function or static +error: attribute should be applied to a function or static+  --> $DIR/issue-43106-gating-of-builtin-attrs-error.rs:23:1+   |+LL | / #![deny(unused_attributes)]+LL | |+LL | |+LL | |+...  |+LL | | #![no_mangle]+   | | ^^^^^^^^^^^^^+...  |+LL | |+LL | | fn main() {}+   | |____________- not a function or static

Highlighting the entire crate span is a bit confusing here. I've not tested but maybe passing DUMMY_SP to check_attributes instead of tcx.hir().span(CRATE_HIR_ID) might work to clean this up.

GuillaumeGomez

comment created time in 24 days

PullRequestReviewEvent
PullRequestReviewEvent

pull request commentrust-lang/rust

Doc alias name restriction

Single quotes can also be used for exact search: https://github.com/rust-lang/rust/blob/a585aaefb662ae26f8675955f26fad9be4fea96b/src/librustdoc/html/static/main.js#L1077

Assuming that's the reason to disallow double quotes then surely we shouldn't allow single quotes as well?

If you search for an alias surrounded by quotes: https://doc.rust-lang.org/nightly/std/?search=%22reduce%22 then the alias doesn't show up in the results. Is that a bug?

GuillaumeGomez

comment created time in 24 days

pull request commentrust-lang/rust

Add missing_docs lint to the rustdoc lint group

When the rustdoc lint group was added in #56689 missing_docs was deliberately left out. Adding it would be changing what the group is for.

GuillaumeGomez

comment created time in a month

pull request commentrust-lang/rust

Add check for doc alias attribute at crate level

Apart from a few questions about the test changes this looks good to me.

I'm going to hand this over this over to the compiler team though because this is not really a rustdoc change anymore and is introducing new errors. Also to make sure we haven't missed an obvious better way to check crate level attributes.

r? @matthewjasper

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

 #![forbid(x5200)] //~ WARN unknown lint: `x5200` #![deny(x5100)] //~ WARN unknown lint: `x5100` #![macro_use] // (allowed if no argument; see issue-43160-gating-of-macro_use.rs)-#![macro_export] //~ WARN unused attribute // skipping testing of cfg // skipping testing of cfg_attr-#![main] //~ WARN unused attribute-#![start] //~ WARN unused attribute-// see issue-43106-gating-of-test.rs for crate-level; but non crate-level is below at "4200"-// see issue-43106-gating-of-bench.rs for crate-level; but non crate-level is below at "4100"-#![repr()]-//~^ WARN unused attribute-#![path = "3800"] //~ WARN unused attribute-#![automatically_derived] //~ WARN unused attribute-#![no_mangle]-#![no_link] //~ WARN unused attribute

Why were these removed? If they're now errors then they should be moved to issue-43106-gating-of-builtin-attrs-error.rs or another dedicated test to make sure they stay errors.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

  // ignore-tidy-linelength -// Crate-level is accepted, though it is almost certainly unused?-#![inline]

Did this attribute need to be removed? If this now produces as error then it should stay so the UI test can make sure it stays an error.

GuillaumeGomez

comment created time in a month

PullRequestReviewEvent
PullRequestReviewEvent

pull request commentrust-lang/rust

Reexported item lints

It's not possible to fix #77254 until this is fixed. Rustdoc doesn't have enough information to tell what module the docs came from, all it has is the CrateId of the Span.

I don't really see how this PR is providing that information. This is creating separate ImportItems but the actual attributes on the inlined item are still the same. I think what needs to be done is keep track of which items each attributes come from in https://github.com/rust-lang/rust/blob/4d52dc4790cfaf3f23ff219c9a9932be2bfcd53e/src/librustdoc/clean/inline.rs#L304 somehow. If we did that then we could use that to decide where to resolve links from and whether to emit broken_intra_doc_links for each line of the docs separately. Then we wouldn't need the extra ImportItems.

If you want I can make a PR on top of this one fixing both at the same time, so that it's always possible to fix the warnings.

That would be useful but if you think the changes in this PR are really needed then I guess it can get merged separately.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Reexported item lints

 impl Clean<Vec<Item>> for doctree::Import<'_> {         let inner = if self.glob {             if !denied {                 let mut visited = FxHashSet::default();-                if let Some(items) = inline::try_inline_glob(cx, path.res, &mut visited) {+                if let Some(mut items) = inline::try_inline_glob(cx, path.res, &mut visited) {+                    items.push(Item {+                        name: None,+                        attrs: self.attrs.clean(cx),+                        source: self.span.clean(cx),+                        def_id: cx.tcx.hir().local_def_id(self.id).to_def_id(),+                        visibility: self.vis.clean(cx),+                        stability: None,+                        deprecation: None,+                        inner: ImportItem(Import::new_glob(resolve_use_source(cx, path), false)),+                    });

I've just noticed that the docs on glob imports are completely ignored so there is no need to do anything for globs.

GuillaumeGomez

comment created time in a month

PullRequestReviewEvent

Pull request review commentrust-lang/rust

Reexported item lints

 impl Clean<Vec<Item>> for doctree::ExternCrate<'_> {  impl Clean<Vec<Item>> for doctree::Import<'_> {     fn clean(&self, cx: &DocContext<'_>) -> Vec<Item> {+        // We need this comparison because some imports (for std types for example)+        // are "inserted" as well but directly by the compiler and they should not be+        // taken into account.+        if self.span.is_dummy() {+            return Vec::new();+        }

use std::prelude::v1::*; imports are never inlined so I don't see what that has to do with this PR which is only changing behavior for imports that are inlined.

The issue I had was simply that a weird error message appeared with missing doc example (when I was forcing the check to test it) with a span pointing to nowhere. So literally: we can't test it.

If you can't write a rustdoc-ui test or at least provide instructions on how to reproduce this issue then this code needs to be deleted.

GuillaumeGomez

comment created time in a month

PullRequestReviewEvent

pull request commentrust-lang/rust

Reexported item lints

Fixes #77230

This PR isn't actually doing anything related to #77230 so that should be removed from the PR comment. FWIW is disagree with emitting lints, including broken_intra_doc_links, for items in external crates like #77230 is suggesting.

What this PR is doing is emitting broken_intra_doc_links for docs applied to pub use statements that point to external items and are inlined. I think does this makes sense because these docs are only displayed in the current crate. However, the links will still be broken (#77254) so I think #77254 should be fixed first so after you fix the warnings you actually get working links.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Reexported item lints

 impl Clean<Vec<Item>> for doctree::ExternCrate<'_> {  impl Clean<Vec<Item>> for doctree::Import<'_> {     fn clean(&self, cx: &DocContext<'_>) -> Vec<Item> {+        // We need this comparison because some imports (for std types for example)+        // are "inserted" as well but directly by the compiler and they should not be+        // taken into account.+        if self.span.is_dummy() {+            return Vec::new();+        }

What exactly is this for? Can you provide some examples, or even better, a test which fails without this check?

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Reexported item lints

 fn item_module(w: &mut Buffer, cx: &Context, item: &clean::Item, items: &[clean:             }              clean::ImportItem(ref import) => {-                write!(-                    w,-                    "<tr><td><code>{}{}</code></td></tr>",-                    myitem.visibility.print_with_space(),-                    import.print()-                );+                if import.should_be_displayed {

This check isn't needs because items are already filtered with is_stripped above.

GuillaumeGomez

comment created time in a month

PullRequestReviewEvent
PullRequestReviewEvent

pull request commentrust-lang/rust

Reexported item lints

This now displays re-exports for items even when they have been inlined. Here's std for example:

image

That can't be intentional, right?

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Resolve `crate` in intra-doc links properly across crates

 impl<K: Ord, V> BTreeMap<K, V> {     /// types that can be `==` without being identical. See the [module-level     /// documentation] for more.     ///-    /// [module-level documentation]: crate::collections#insert-and-complex-keys+    /// [module-level documentation]: index.html#insert-and-complex-keys

I see.

jyn514

comment created time in a month

PullRequestReviewEvent

Pull request review commentrust-lang/rust

Resolve `crate` in intra-doc links properly across crates

 impl<K: Ord, V> BTreeMap<K, V> {     /// types that can be `==` without being identical. See the [module-level     /// documentation] for more.     ///-    /// [module-level documentation]: crate::collections#insert-and-complex-keys+    /// [module-level documentation]: index.html#insert-and-complex-keys

What's going on here? Is this a regression?

jyn514

comment created time in a month

Pull request review commentrust-lang/rust

Revamp rustdoc docs about documentation using `cfg`

 pub struct UnixToken; Here, the respective tokens can only be used by dependent crates on their respective platforms, but they will both appear in documentation. +### Interactions between platform-specific docs++Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each+platform (such a magic wand has been called the ['holy grail of rustdoc'][#1998]). Instead,+it sees *all* of your code at once, the same way the Rust compiler would if you passed it+`--cfg doc`. However, Rustdoc has a trick up its sleeve to handle platform-specific code if it+*does* receive it.++To document your crate, Rustdoc only needs to know the public signature of your functions.+In particular, it doesn't have know how any of your functions are implemented, so it ignores+all type errors and name resolution errors with function bodies. Note that this does *not*+work for anything outside a function body: since Rustdoc documents your types, it has to+know what those types are! For example, this code will work regardless of the platform:++<!-- `ignore` because doc-tests are run with `rustc`, not `rustdoc` -->+```ignore+pub fn f() {+	use std::os::windows::ffi::OsStrExt;+}+```++but this will not, because the unknown type is part of the function signature:++```compile_fail+pub fn f() -> std::os::windows::ffi::EncodeWide {
```ignore
pub fn f<'a>() -> std::os::windows::ffi::EncodeWide<'a> {

The lifetime is needed for this example to be valid rust and this test will need to be marked ignore otherwise the test will fail on Windows by compiling successfully.

jyn514

comment created time in a month

Pull request review commentrust-lang/rust

Revamp rustdoc docs about documentation using `cfg`

 pub struct UnixToken; Here, the respective tokens can only be used by dependent crates on their respective platforms, but they will both appear in documentation. +### Interactions between platform-specific docs++Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each+platform (such a magic wand has been called the ['holy grail of rustdoc'][#1998]). Instead,+it sees *all* of your code at once, the same way the Rust compiler would if you passed it+`--cfg doc`. However, Rustdoc has a trick up its sleeve to handle platform-specific code if it+*does* receive it.++To document your crate, Rustdoc only needs to know the public signature of your functions.+In particular, it doesn't have know how any of your functions are implemented, so it ignores+all type errors and name resolution errors with function bodies. Note that this does *not*+work for anything outside a function body: since Rustdoc documents your types, it has to+know what those types are! For example, this code will work regardless of the platform:++<!-- `ignore` because doc-tests are run with `rustc`, not `rustdoc` -->+```ignore+pub fn f() {+	use std::os::windows::ffi::OsStrExt;
    use std::os::windows::ffi::OsStrExt;
jyn514

comment created time in a month

Pull request review commentrust-lang/rust

Revamp rustdoc docs about documentation using `cfg`

 pub struct UnixToken; Here, the respective tokens can only be used by dependent crates on their respective platforms, but they will both appear in documentation. +### Interactions between platform-specific docs++Rustdoc does not have a magic way to compile documentation 'as-if' you'd run it once for each+platform (such a magic wand has been called the ['holy grail of rustdoc'][#1998]). Instead,+it sees *all* of your code at once, the same way the Rust compiler would if you passed it+`--cfg doc`. However, Rustdoc has a trick up its sleeve to handle platform-specific code if it+*does* receive it.++To document your crate, Rustdoc only needs to know the public signature of your functions.+In particular, it doesn't have know how any of your functions are implemented, so it ignores+all type errors and name resolution errors with function bodies. Note that this does *not*+work for anything outside a function body: since Rustdoc documents your types, it has to+know what those types are! For example, this code will work regardless of the platform:++<!-- `ignore` because doc-tests are run with `rustc`, not `rustdoc` -->+```ignore+pub fn f() {+	use std::os::windows::ffi::OsStrExt;+}+```++but this will not, because the unknown type is part of the function signature:++```compile_fail+pub fn f() -> std::os::windows::ffi::EncodeWide {+	unimplemented!()
    unimplemented!()
jyn514

comment created time in a month

Pull request review commentrust-lang/rust

Revamp rustdoc docs about documentation using `cfg`

 Note: Because of how `macro_rules` macros are scoped in Rust, the intra-doc link These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler and enabled with a `#![feature(...)]` attribute in your crate. -### Documenting platform-/feature-specific information+### `#[doc(cfg)]`: Telling rustdoc what platforms documentation is present on

It's not just for platforms, it's what cargo features need to be enabled for example.

This line conflicts with #76849 so maybe #76849 should be closed in favor of this?

jyn514

comment created time in a month

PullRequestReviewEvent
PullRequestReviewEvent

pull request commentrust-lang/rust

Unclosed html tag lint

@bors r-

This ICEs on:

//! <p>💩<p>
thread 'rustc' panicked at 'byte index 4 is not a char boundary; it is inside '💩' (bytes 3..7) of `<p>💩<p>`', src\librustdoc\passes\mod.rs:352:25

<hr>

Fixes #67799.

While this is work towards fixing #67799 it certainly can't close the issue. The lint doesn't even trigger for the example given in #67799 because the tag in Vec<Script> starts with a capital letter. HTML tags aren't case sensitive which is something this PR doesn't seem to take into account.

The lint is also not triggering for incomplete tags like:

//! <script

or

//! <!--

which causes the same kinds of problems as in #67799.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add doc alias for pointer primitive

 mod prim_char {} #[stable(feature = "rust1", since = "1.0.0")] mod prim_unit {} +#[doc(alias = "ptr")]+#[doc(alias = "pointer")]

I share @pickfire's confusion here. If you search for pointer the first result is already the primitive page. Why would we also need #[doc(alias = "pointer")]?

If also confused and concerned about the dismissive response to @pickfire's question. As far as my interpretation is concerned it's a perfectly valid question and this is the correct place to ask it. I would also like to know the answer, maybe I can be a better response than RTFM.

GuillaumeGomez

comment created time in a month

PullRequestReviewEvent

delete branch ollie27/rust_doc_test

delete branch : gh-pages

delete time in a month

create barnchollie27/rust_doc_test

branch : gh-pages-old

created branch time in a month

issue commentrust-lang/rust

Regression in nightly-2020-09-23: "missing `as_flags` in implementation" of OpenOptionsExt

I was under the impression that the *Ext traits were not intended to be implemented outside of std which means this is really an issue with async-std which shouldn't have implemented OpenOptionsExt at all.

std::os::unix::process::CommandExt for example has had several methods added to it since 1.0. Is there something different with OpenOptionsExt or is this just that it was implemented by a popular crate?

dtolnay

comment created time in a month

pull request commentrust-lang/rust

Add --no-source option flag to rustdoc

@bors r-

New features require at least an FCP.

An issue with --no-source is that there is no way for rustdoc to know if a dependency has been documented with that flag so [src] links to that depedency would be broken. With the crate level attribute rustdoc can avoid generating broken [src] links to dependencies. Admittedly rustdoc doesn't yet do that but it could and should: #55957.

GuillaumeGomez

comment created time in a month

issue closedrust-lang/rust

Rustdoc files have naming collisions on case-insensitive file systems

Rust is case-sensitive, but some filesystems (especially on Windows) are not. This could cause overlaps in names for the files generated by rustdoc, such as the following:

struct Command; // page currently generated at `struct.Command.html`
struct command {} // page currently generated at `struct.command.html`

This is somewhat mitigated by the non_camel_case_types lint, which warns if you don't use the customary capitalization for the items.

@nemo157 has kindly conducted a survey of the docs.rs documentation and found that there are about 700,000 items that currently overlap, out of 308,064,859 total items in the inventory, so 0.23% files conflict.

It's not clear how many users this impacts. Are there lots of people generating docs for crates with an overlap, and are they documenting on Windows? @retep998 said the behavior in that case will be that that whichever file is generated first will determine the name and whichever one is last will determine the contents.

closed time in a month

jyn514

issue commentrust-lang/rust

Rustdoc files have naming collisions on case-insensitive file systems

Duplicate of #25879

jyn514

comment created time in a month

pull request commentrust-lang/rust

Revamp rustdoc docs about documentation using `cfg`

* Move it out of `unstable-features`. It's not unstable.

#[doc(cfg(...))] is still unstable so why were it's docs moved?

jyn514

comment created time in a month

Pull request review commentrust-lang/rust

emit lints warnings on doc private if --document-private-items is used

 pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {      find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None); +    if cx.render_options.document_private+        && dox.is_empty()+        && !matches!(item.inner, clean::ImportItem(..))+    {+        let sp = span_of_attrs(&item.attrs).unwrap_or(item.source.span());+        if !sp.is_dummy() {+            cx.tcx.struct_span_lint_hir(rustc_lint::builtin::MISSING_DOCS, hir_id, sp, |lint| {+                lint.build("missing documentation").emit()+            });+        }+    }

I don't like the idea of lints changing behavior based on --document-private-items. I think a separate lint to for private items would be the right solution here. Such a lint already exists in clippy so the only possible next step would be to move that lint to rustc.

GuillaumeGomez

comment created time in a month

PullRequestReviewEvent

Pull request review commentrust-lang/rust

Specialize format! for simple "{}" case

 macro_rules! vec { /// format!("hello {}", "world!"); /// format!("x = {}, y = {y}", 10, y = 30); /// ```+#[allow_internal_unstable(display_type_guard)] #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] macro_rules! format {+    // A faster path for simple format! calls.+    ("{}", $($arg:tt,?)+) => {{

but that doesn't include any examples that I can see which match the format!("{}", x = 1); case that I can see

That's because it's a bug and shouldn't be accepted: #45256

workingjubilee

comment created time in a month

PullRequestReviewEvent

issue commentrust-lang/rust

Clean up doc_alias feature

Actually, the " character has a meaning in the search (for "exact" search).

That doesn't work for #[doc(alias = "...")] though, maybe it should?

But instead of just removing it, maybe we should instead emit an error when we encounter it.

It would make sense to restrict allowed characters because even whitespace is allowed at the moment which seems questionable.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

 fn is_c_like_enum(item: &Item<'_>) -> bool { fn check_mod_attrs(tcx: TyCtxt<'_>, module_def_id: LocalDefId) {     tcx.hir()         .visit_item_likes_in_module(module_def_id, &mut CheckAttrVisitor { tcx }.as_deep_visitor());+    if tcx.hir().local_def_id(CRATE_HIR_ID) == module_def_id {+        for attr in tcx.hir().krate_attrs() {+            CheckAttrVisitor { tcx }.check_doc_alias(attr, CRATE_HIR_ID, Target::Mod);+        }

We could call check_attributes here which should fix #64734 and #69365 while we're at it.

If you want to just apply this to the #[doc] attribute for now though this will need a if self.tcx.sess.check_name(attr, sym::doc) check.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

 impl CheckAttrVisitor<'tcx> {                                 )                                 .emit();                         }+                        if attr.style == AttrStyle::Inner && CRATE_HIR_ID == hir_id {+                            self.tcx+                                .sess+                                .struct_span_err(+                                    meta.span(),+                                    "`#![doc(alias = \"...\")]` isn't allowed as a crate \+                                     level attribute",+                                )+                                .emit();
                                .emit();
                            return false;

If we emit an error then we should return false like the other attribute checks do.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

 impl CheckAttrVisitor<'tcx> {                                 )                                 .emit();                         }+                        if attr.style == AttrStyle::Inner && CRATE_HIR_ID == hir_id {
                        if CRATE_HIR_ID == hir_id {

The attribute style check isn't needed.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

 impl CheckAttrVisitor<'tcx> {                                 )                                 .emit();
                                .emit();
                            return false;

This is preexisting.

GuillaumeGomez

comment created time in a month

Pull request review commentrust-lang/rust

Add check for doc alias attribute at crate level

 fn is_c_like_enum(item: &Item<'_>) -> bool { fn check_mod_attrs(tcx: TyCtxt<'_>, module_def_id: LocalDefId) {     tcx.hir()         .visit_item_likes_in_module(module_def_id, &mut CheckAttrVisitor { tcx }.as_deep_visitor());+    if tcx.hir().local_def_id(CRATE_HIR_ID) == module_def_id {
    if module_def_id.is_top_level_module() {
GuillaumeGomez

comment created time in a month

more