2 files changed, 178 insertions, 102 deletions

diff --git a/xtask/src/codegen/gen_assists_docs.rs b/xtask/src/codegen/gen_assists_docs.rs
index 4bd6b5f0c..6c1be5350 100644
--- a/xtask/src/codegen/gen_assists_docs.rs
+++ b/xtask/src/codegen/gen_assists_docs.rs
@@ -1,102 +1,112 @@
 //! Generates `assists.md` documentation.
 
-use std::{fs, path::Path};
+use std::{fmt, fs, path::Path};
 
 use crate::{
-    codegen::{self, extract_comment_blocks_with_empty_lines, Mode},
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
     project_root, rust_files, Result,
 };
 
 pub fn generate_assists_docs(mode: Mode) -> Result<()> {
-    let assists = collect_assists()?;
+    let assists = Assist::collect()?;
     generate_tests(&assists, mode)?;
-    generate_docs(&assists, mode)?;
+
+    let contents = assists.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = contents.trim().to_string() + "\n";
+    let dst = project_root().join("docs/user/generated_assists.adoc");
+    codegen::update(&dst, &contents, mode)?;
+
     Ok(())
 }
 
 #[derive(Debug)]
 struct Assist {
     id: String,
+    location: Location,
     doc: String,
     before: String,
     after: String,
 }
 
-fn hide_hash_comments(text: &str) -> String {
-    text.split('\n') // want final newline
-        .filter(|&it| !(it.starts_with("# ") || it == "#"))
-        .map(|it| format!("{}\n", it))
-        .collect()
-}
-
-fn reveal_hash_comments(text: &str) -> String {
-    text.split('\n') // want final newline
-        .map(|it| {
-            if it.starts_with("# ") {
-                &it[2..]
-            } else if it == "#" {
-                ""
-            } else {
-                it
-            }
-        })
-        .map(|it| format!("{}\n", it))
-        .collect()
-}
-
-fn collect_assists() -> Result<Vec<Assist>> {
-    let mut res = Vec::new();
-    for path in rust_files(&project_root().join(codegen::ASSISTS_DIR)) {
-        collect_file(&mut res, path.as_path())?;
-    }
-    res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
-    return Ok(res);
-
-    fn collect_file(acc: &mut Vec<Assist>, path: &Path) -> Result<()> {
-        let text = fs::read_to_string(path)?;
-        let comment_blocks = extract_comment_blocks_with_empty_lines(&text);
-
-        for block in comment_blocks {
-            // FIXME: doesn't support blank lines yet, need to tweak
-            // `extract_comment_blocks` for that.
-            let mut lines = block.iter();
-            let first_line = lines.next().unwrap();
-            if !first_line.starts_with("Assist: ") {
-                continue;
-            }
-            let id = first_line["Assist: ".len()..].to_string();
-            assert!(
-                id.chars().all(|it| it.is_ascii_lowercase() || it == '_'),
-                "invalid assist id: {:?}",
-                id
-            );
-
-            let doc = take_until(lines.by_ref(), "```").trim().to_string();
-            assert!(
-                doc.chars().next().unwrap().is_ascii_uppercase() && doc.ends_with('.'),
-                "\n\n{}: assist docs should be proper sentences, with capitalization and a full stop at the end.\n\n{}\n\n",
-                id, doc,
-            );
-
-            let before = take_until(lines.by_ref(), "```");
-
-            assert_eq!(lines.next().unwrap().as_str(), "->");
-            assert_eq!(lines.next().unwrap().as_str(), "```");
-            let after = take_until(lines.by_ref(), "```");
-            acc.push(Assist { id, doc, before, after })
+impl Assist {
+    fn collect() -> Result<Vec<Assist>> {
+        let mut res = Vec::new();
+        for path in rust_files(&project_root().join(codegen::ASSISTS_DIR)) {
+            collect_file(&mut res, path.as_path())?;
         }
+        res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
+        return Ok(res);
+
+        fn collect_file(acc: &mut Vec<Assist>, path: &Path) -> Result<()> {
+            let text = fs::read_to_string(path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Assist", &text);
+
+            for block in comment_blocks {
+                // FIXME: doesn't support blank lines yet, need to tweak
+                // `extract_comment_blocks` for that.
+                let id = block.id;
+                assert!(
+                    id.chars().all(|it| it.is_ascii_lowercase() || it == '_'),
+                    "invalid assist id: {:?}",
+                    id
+                );
+                let mut lines = block.contents.iter();
+
+                let doc = take_until(lines.by_ref(), "```").trim().to_string();
+                assert!(
+                    doc.chars().next().unwrap().is_ascii_uppercase() && doc.ends_with('.'),
+                    "\n\n{}: assist docs should be proper sentences, with capitalization and a full stop at the end.\n\n{}\n\n",
+                    id, doc,
+                );
+
+                let before = take_until(lines.by_ref(), "```");
+
+                assert_eq!(lines.next().unwrap().as_str(), "->");
+                assert_eq!(lines.next().unwrap().as_str(), "```");
+                let after = take_until(lines.by_ref(), "```");
+                let location = Location::new(path.to_path_buf(), block.line);
+                acc.push(Assist { id, location, doc, before, after })
+            }
 
-        fn take_until<'a>(lines: impl Iterator<Item = &'a String>, marker: &str) -> String {
-            let mut buf = Vec::new();
-            for line in lines {
-                if line == marker {
-                    break;
+            fn take_until<'a>(lines: impl Iterator<Item = &'a String>, marker: &str) -> String {
+                let mut buf = Vec::new();
+                for line in lines {
+                    if line == marker {
+                        break;
+                    }
+                    buf.push(line.clone());
                 }
-                buf.push(line.clone());
+                buf.join("\n")
             }
-            buf.join("\n")
+            Ok(())
         }
-        Ok(())
+    }
+}
+
+impl fmt::Display for Assist {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let before = self.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
+        let after = self.after.replace("<|>", "┃");
+        writeln!(
+            f,
+            "[discrete]\n=== `{}`
+**Source:** {}
+
+{}
+
+.Before
+```rust
+{}```
+
+.After
+```rust
+{}```",
+            self.id,
+            self.location,
+            self.doc,
+            hide_hash_comments(&before),
+            hide_hash_comments(&after)
+        )
     }
 }
 
@@ -127,33 +137,24 @@ r#####"
     codegen::update(&project_root().join(codegen::ASSISTS_TESTS), &buf, mode)
 }
 
-fn generate_docs(assists: &[Assist], mode: Mode) -> Result<()> {
-    let mut buf = String::from(
-        "# Assists\n\nCursor position or selection is signified by `┃` character.\n\n",
-    );
-
-    for assist in assists {
-        let before = assist.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
-        let after = assist.after.replace("<|>", "┃");
-        let docs = format!(
-            "
-## `{}`
-
-{}
-
-```rust
-// BEFORE
-{}
-// AFTER
-{}```
-",
-            assist.id,
-            assist.doc,
-            hide_hash_comments(&before),
-            hide_hash_comments(&after)
-        );
-        buf.push_str(&docs);
-    }
+fn hide_hash_comments(text: &str) -> String {
+    text.split('\n') // want final newline
+        .filter(|&it| !(it.starts_with("# ") || it == "#"))
+        .map(|it| format!("{}\n", it))
+        .collect()
+}
 
-    codegen::update(&project_root().join(codegen::ASSISTS_DOCS), &buf, mode)
+fn reveal_hash_comments(text: &str) -> String {
+    text.split('\n') // want final newline
+        .map(|it| {
+            if it.starts_with("# ") {
+                &it[2..]
+            } else if it == "#" {
+                ""
+            } else {
+                it
+            }
+        })
+        .map(|it| format!("{}\n", it))
+        .collect()
 }
diff --git a/xtask/src/codegen/gen_feature_docs.rs b/xtask/src/codegen/gen_feature_docs.rs
new file mode 100644
index 000000000..31bc3839d
--- /dev/null
+++ b/xtask/src/codegen/gen_feature_docs.rs
@@ -0,0 +1,75 @@
+//! Generates `assists.md` documentation.
+
+use std::{fmt, fs, path::PathBuf};
+
+use crate::{
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
+    project_root, rust_files, Result,
+};
+
+pub fn generate_feature_docs(mode: Mode) -> Result<()> {
+    let features = Feature::collect()?;
+    let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = contents.trim().to_string() + "\n";
+    let dst = project_root().join("docs/user/generated_features.adoc");
+    codegen::update(&dst, &contents, mode)?;
+    Ok(())
+}
+
+#[derive(Debug)]
+struct Feature {
+    id: String,
+    location: Location,
+    doc: String,
+}
+
+impl Feature {
+    fn collect() -> Result<Vec<Feature>> {
+        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<Feature>, path: PathBuf) -> Result<()> {
+            let text = fs::read_to_string(&path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Feature", &text);
+
+            for block in comment_blocks {
+                let id = block.id;
+                assert!(is_valid_feature_name(&id), "invalid feature name: {:?}", id);
+                let doc = block.contents.join("\n");
+                let location = Location::new(path.clone(), block.line);
+                acc.push(Feature { id, location, doc })
+            }
+
+            Ok(())
+        }
+    }
+}
+
+fn is_valid_feature_name(feature: &str) -> bool {
+    'word: for word in feature.split_whitespace() {
+        for &short in ["to", "and"].iter() {
+            if word == short {
+                continue 'word;
+            }
+        }
+        for &short in ["To", "And"].iter() {
+            if word == short {
+                return false;
+            }
+        }
+        if !word.starts_with(char::is_uppercase) {
+            return false;
+        }
+    }
+    true
+}
+
+impl fmt::Display for Feature {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
+    }
+}