Merge #4083

4083: Smol documentation for ast nodes r=matklad a=Veetaha

There is a tremendous amount of TODOs to clarify the topics I am not certain about.
Please @matklad, @edwin0cheng review carefully, I even left some mentions of your names in todos to put your attention where you most probably can give comments.

In order to simplify the review, I separated the codegen (i.e. changes in `ast/generated/nodes.rs`) from `ast_src` changes (they in fact just duplicate one another) into two commits.

Also, I had to hack a little bit to let the docs be generated as doc comments and not as doc attributes because it's easier to read them this way and IIRC we don't support hints for `#[doc = ""]` attributes for now...

Closes #3682 

Co-authored-by: veetaha <[email protected]>

1 files changed, 23 insertions, 2 deletions

diff --git a/xtask/src/codegen/gen_syntax.rs b/xtask/src/codegen/gen_syntax.rs
index 8028575c5..19d5594f5 100644
--- a/xtask/src/codegen/gen_syntax.rs
+++ b/xtask/src/codegen/gen_syntax.rs
@@ -3,7 +3,7 @@
 //! Specifically, it generates the `SyntaxKind` enum and a number of newtype
 //! wrappers around `SyntaxNode` which implement `ra_syntax::AstNode`.
 
-use std::collections::HashSet;
+use std::{collections::HashSet, fmt::Write};
 
 use proc_macro2::{Punct, Spacing};
 use quote::{format_ident, quote};
@@ -102,6 +102,7 @@ fn generate_nodes(kinds: KindsSrc<'_>, grammar: AstSrc<'_>) -> Result<String> {
             });
             (
                 quote! {
+                    #[pretty_doc_comment_placeholder_workaround]
                     #[derive(Debug, Clone, PartialEq, Eq, Hash)]
                     pub struct #name {
                         pub(crate) syntax: SyntaxNode,
@@ -145,6 +146,7 @@ fn generate_nodes(kinds: KindsSrc<'_>, grammar: AstSrc<'_>) -> Result<String> {
 
             (
                 quote! {
+                    #[pretty_doc_comment_placeholder_workaround]
                     #[derive(Debug, Clone, PartialEq, Eq, Hash)]
                     pub enum #name {
                         #(#variants(#variants),)*
@@ -230,10 +232,29 @@ fn generate_nodes(kinds: KindsSrc<'_>, grammar: AstSrc<'_>) -> Result<String> {
     };
 
     let ast = ast.to_string().replace("T ! [ ", "T![").replace(" ] )", "])");
-    let pretty = crate::reformat(ast)?.replace("#[derive", "\n#[derive");
+
+    let mut res = String::with_capacity(ast.len() * 2);
+
+    let mut docs =
+        grammar.nodes.iter().map(|it| it.doc).chain(grammar.enums.iter().map(|it| it.doc));
+
+    for chunk in ast.split("# [ pretty_doc_comment_placeholder_workaround ]") {
+        res.push_str(chunk);
+        if let Some(doc) = docs.next() {
+            write_doc_comment(doc, &mut res);
+        }
+    }
+
+    let pretty = crate::reformat(res)?;
     Ok(pretty)
 }
 
+fn write_doc_comment(contents: &[&str], dest: &mut String) {
+    for line in contents {
+        writeln!(dest, "///{}", line).unwrap();
+    }
+}
+
 fn generate_syntax_kinds(grammar: KindsSrc<'_>) -> Result<String> {
     let (single_byte_tokens_values, single_byte_tokens): (Vec<_>, Vec<_>) = grammar
         .punct