Merge #6266

6266: Generate diagnostics docs r=matklad a=popzxc

Resolves #6215


Co-authored-by: Igor Aleksanov <[email protected]>

Author: bors[bot]

.gitignore

@@ -9,3 +9,4 @@ crates/*/target
 .vscode/settings.json
 generated_assists.adoc
 generated_features.adoc
+generated_diagnostic.adoc

crates/hir_def/src/diagnostics.rs

@@ -7,6 +7,9 @@ use syntax::{ast, AstPtr, SyntaxNodePtr};
 
 use hir_expand::{HirFileId, InFile};
 
+// Diagnostic: unresolved-module
+//
+// This diagnostic is triggered if rust-analyzer is unable to discover referred module.
 #[derive(Debug)]
 pub struct UnresolvedModule {
     pub file: HirFileId,
@@ -29,6 +32,9 @@ impl Diagnostic for UnresolvedModule {
     }
 }
 
+// Diagnostic: unresolved-extern-crate
+//
+// This diagnostic is triggered if rust-analyzer is unable to discover referred extern crate.
 #[derive(Debug)]
 pub struct UnresolvedExternCrate {
     pub file: HirFileId,
@@ -50,6 +56,9 @@ impl Diagnostic for UnresolvedExternCrate {
     }
 }
 
+// Diagnostic: unresolved-import
+//
+// This diagnostic is triggered if rust-analyzer is unable to discover imported module.
 #[derive(Debug)]
 pub struct UnresolvedImport {
     pub file: HirFileId,

crates/hir_ty/src/diagnostics.rs

@@ -36,6 +36,9 @@ pub fn validate_body(db: &dyn HirDatabase, owner: DefWithBodyId, sink: &mut Diag
     validator.validate_body(db);
 }
 
+// Diagnostic: no-such-field
+//
+// This diagnostic is triggered if created structure does not have field provided in record.
 #[derive(Debug)]
 pub struct NoSuchField {
     pub file: HirFileId,
@@ -60,6 +63,17 @@ impl Diagnostic for NoSuchField {
     }
 }
 
+// Diagnostic: missing-structure-fields
+//
+// This diagnostic is triggered if record lacks some fields that exist in the corresponding structure.
+//
+// Example:
+//
+// ```rust
+// struct A { a: u8, b: u8 }
+//
+// let a = A { a: 10 };
+// ```
 #[derive(Debug)]
 pub struct MissingFields {
     pub file: HirFileId,
@@ -96,6 +110,21 @@ impl Diagnostic for MissingFields {
     }
 }
 
+// Diagnostic: missing-pat-fields
+//
+// This diagnostic is triggered if pattern lacks some fields that exist in the corresponding structure.
+//
+// Example:
+//
+// ```rust
+// struct A { a: u8, b: u8 }
+//
+// let a = A { a: 10, b: 20 };
+//
+// if let A { a } = a {
+//     // ...
+// }
+// ```
 #[derive(Debug)]
 pub struct MissingPatFields {
     pub file: HirFileId,
@@ -130,6 +159,9 @@ impl Diagnostic for MissingPatFields {
     }
 }
 
+// Diagnostic: missing-match-arm
+//
+// This diagnostic is triggered if `match` block is missing one or more match arms.
 #[derive(Debug)]
 pub struct MissingMatchArms {
     pub file: HirFileId,
@@ -152,6 +184,17 @@ impl Diagnostic for MissingMatchArms {
     }
 }
 
+// Diagnostic: missing-ok-in-tail-expr
+//
+// This diagnostic is triggered if block that should return `Result` returns a value not wrapped in `Ok`.
+//
+// Example:
+//
+// ```rust
+// fn foo() -> Result<u8, ()> {
+//     10
+// }
+// ```
 #[derive(Debug)]
 pub struct MissingOkInTailExpr {
     pub file: HirFileId,
@@ -173,6 +216,9 @@ impl Diagnostic for MissingOkInTailExpr {
     }
 }
 
+// Diagnostic: break-outside-of-loop
+//
+// This diagnostic is triggered if `break` keyword is used outside of a loop.
 #[derive(Debug)]
 pub struct BreakOutsideOfLoop {
     pub file: HirFileId,
@@ -194,6 +240,9 @@ impl Diagnostic for BreakOutsideOfLoop {
     }
 }
 
+// Diagnostic: missing-unsafe
+//
+// This diagnostic is triggered if operation marked as `unsafe` is used outside of `unsafe` function or block.
 #[derive(Debug)]
 pub struct MissingUnsafe {
     pub file: HirFileId,
@@ -215,6 +264,9 @@ impl Diagnostic for MissingUnsafe {
     }
 }
 
+// Diagnostic: mismatched-arg-count
+//
+// This diagnostic is triggered if function is invoked with an incorrect amount of arguments.
 #[derive(Debug)]
 pub struct MismatchedArgCount {
     pub file: HirFileId,
@@ -264,6 +316,9 @@ impl fmt::Display for CaseType {
     }
 }
 
+// Diagnostic: incorrect-ident-case
+//
+// This diagnostic is triggered if item name doesn't follow https://doc.rust-lang.org/1.0.0/style/style/naming/README.html[Rust naming convention].
 #[derive(Debug)]
 pub struct IncorrectCase {
     pub file: HirFileId,

xtask/src/codegen.rs

@@ -10,6 +10,7 @@ mod gen_parser_tests;
 mod gen_assists_docs;
 mod gen_feature_docs;
 mod gen_features;
+mod gen_diagnostic_docs;
 
 use std::{
     fmt, mem,
@@ -21,6 +22,7 @@ use crate::{ensure_rustfmt, project_root, Result};
 
 pub use self::{
     gen_assists_docs::{generate_assists_docs, generate_assists_tests},
+    gen_diagnostic_docs::generate_diagnostic_docs,
     gen_feature_docs::generate_feature_docs,
     gen_features::generate_features,
     gen_parser_tests::generate_parser_tests,
@@ -47,6 +49,7 @@ impl CodegenCmd {
         generate_assists_tests(Mode::Overwrite)?;
         generate_assists_docs(Mode::Overwrite)?;
         generate_feature_docs(Mode::Overwrite)?;
+        generate_diagnostic_docs(Mode::Overwrite)?;
         Ok(())
     }
 }

xtask/src/codegen/gen_assists_docs.rs

@@ -1,6 +1,6 @@
 //! Generates `assists.md` documentation.
 
-use std::{fmt, fs, path::Path};
+use std::{fmt, path::Path};
 
 use crate::{
     codegen::{self, extract_comment_blocks_with_empty_lines, reformat, Location, Mode, PREAMBLE},
@@ -39,7 +39,7 @@ impl Assist {
         return Ok(res);
 
         fn collect_file(acc: &mut Vec<Assist>, path: &Path) -> Result<()> {
-            let text = fs::read_to_string(path)?;
+            let text = xshell::read_file(path)?;
             let comment_blocks = extract_comment_blocks_with_empty_lines("Assist", &text);
 
             for block in comment_blocks {

xtask/src/codegen/gen_diagnostic_docs.rs

@@ -0,0 +1,74 @@
+//! Generates `assists.md` documentation.
+
+use std::{fmt, path::PathBuf};
+
+use crate::{
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode, PREAMBLE},
+    project_root, rust_files, Result,
+};
+
+pub fn generate_diagnostic_docs(mode: Mode) -> Result<()> {
+    let diagnostics = Diagnostic::collect()?;
+    let contents =
+        diagnostics.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = format!("//{}\n{}\n", PREAMBLE, contents.trim());
+    let dst = project_root().join("docs/user/generated_diagnostic.adoc");
+    codegen::update(&dst, &contents, mode)?;
+    Ok(())
+}
+
+#[derive(Debug)]
+struct Diagnostic {
+    id: String,
+    location: Location,
+    doc: String,
+}
+
+impl Diagnostic {
+    fn collect() -> Result<Vec<Diagnostic>> {
+        let mut res = Vec::new();
+        for path in rust_files(&project_root()) {
+            collect_file(&mut res, path)?;
+        }
+        res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
+        return Ok(res);
+
+        fn collect_file(acc: &mut Vec<Diagnostic>, path: PathBuf) -> Result<()> {
+            let text = xshell::read_file(&path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Diagnostic", &text);
+
+            for block in comment_blocks {
+                let id = block.id;
+                if let Err(msg) = is_valid_diagnostic_name(&id) {
+                    panic!("invalid diagnostic name: {:?}:\n  {}", id, msg)
+                }
+                let doc = block.contents.join("\n");
+                let location = Location::new(path.clone(), block.line);
+                acc.push(Diagnostic { id, location, doc })
+            }
+
+            Ok(())
+        }
+    }
+}
+
+fn is_valid_diagnostic_name(diagnostic: &str) -> Result<(), String> {
+    let diagnostic = diagnostic.trim();
+    if diagnostic.find(char::is_whitespace).is_some() {
+        return Err("Diagnostic names can't contain whitespace symbols".into());
+    }
+    if diagnostic.chars().any(|c| c.is_ascii_uppercase()) {
+        return Err("Diagnostic names can't contain uppercase symbols".into());
+    }
+    if diagnostic.chars().any(|c| !c.is_ascii()) {
+        return Err("Diagnostic can't contain non-ASCII symbols".into());
+    }
+
+    Ok(())
+}
+
+impl fmt::Display for Diagnostic {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
+    }
+}

xtask/src/codegen/gen_feature_docs.rs

@@ -1,6 +1,6 @@
 //! Generates `assists.md` documentation.
 
-use std::{fmt, fs, path::PathBuf};
+use std::{fmt, path::PathBuf};
 
 use crate::{
     codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode, PREAMBLE},
@@ -33,7 +33,7 @@ impl Feature {
         return Ok(res);
 
         fn collect_file(acc: &mut Vec<Feature>, path: PathBuf) -> Result<()> {
-            let text = fs::read_to_string(&path)?;
+            let text = xshell::read_file(&path)?;
             let comment_blocks = extract_comment_blocks_with_empty_lines("Feature", &text);
 
             for block in comment_blocks {

xtask/src/codegen/gen_parser_tests.rs

@@ -124,7 +124,7 @@ fn existing_tests(dir: &Path, ok: bool) -> Result<HashMap<String, (PathBuf, Test
             let file_name = path.file_name().unwrap().to_str().unwrap();
             file_name[5..file_name.len() - 3].to_string()
         };
-        let text = fs::read_to_string(&path)?;
+        let text = xshell::read_file(&path)?;
         let test = Test { name: name.clone(), text, ok };
         if let Some(old) = res.insert(name, (path, test)) {
             println!("Duplicate test: {:?}", old);

xtask/src/release.rs

@@ -52,7 +52,14 @@ https://github.com/sponsors/rust-analyzer[GitHub Sponsors].
         let path = changelog_dir.join(format!("{}-changelog-{}.adoc", today, changelog_n));
         write_file(&path, &contents)?;
 
-        for &adoc in ["manual.adoc", "generated_features.adoc", "generated_assists.adoc"].iter() {
+        for &adoc in [
+            "manual.adoc",
+            "generated_features.adoc",
+            "generated_assists.adoc",
+            "generated_diagnostic.adoc",
+        ]
+        .iter()
+        {
             let src = project_root().join("./docs/user/").join(adoc);
             let dst = website_root.join(adoc);
             cp(src, dst)?;

xtask/tests/tidy.rs

@@ -42,6 +42,7 @@ fn smoke_test_docs_generation() {
     // We don't commit docs to the repo, so we can just overwrite in tests.
     codegen::generate_assists_docs(Mode::Overwrite).unwrap();
     codegen::generate_feature_docs(Mode::Overwrite).unwrap();
+    codegen::generate_diagnostic_docs(Mode::Overwrite).unwrap();
 }
 
 #[test]