xtask/src/codegen/gen_feature_docs.rs

   1 //! Generates `assists.md` documentation.
   2
   3 use std::{fmt, path::PathBuf};
   4
   5 use crate::{
   6     codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode, PREAMBLE},
   7     project_root, rust_files, Result,
   8 };
   9
  10 pub fn generate_feature_docs(mode: Mode) -> Result<()> {
  11     let features = Feature::collect()?;
  12     let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
  13     let contents = format!("//{}\n{}\n", PREAMBLE, contents.trim());
  14     let dst = project_root().join("docs/user/generated_features.adoc");
  15     codegen::update(&dst, &contents, mode)?;
  16     Ok(())
  17 }
  18
  19 #[derive(Debug)]
  20 struct Feature {
  21     id: String,
  22     location: Location,
  23     doc: String,
  24 }
  25
  26 impl Feature {
  27     fn collect() -> Result<Vec<Feature>> {
  28         let mut res = Vec::new();
  29         for path in rust_files(&project_root()) {
  30             collect_file(&mut res, path)?;
  31         }
  32         res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
  33         return Ok(res);
  34
  35         fn collect_file(acc: &mut Vec<Feature>, path: PathBuf) -> Result<()> {
  36             let text = xshell::read_file(&path)?;
  37             let comment_blocks = extract_comment_blocks_with_empty_lines("Feature", &text);
  38
  39             for block in comment_blocks {
  40                 let id = block.id;
  41                 if let Err(msg) = is_valid_feature_name(&id) {
  42                     panic!("invalid feature name: {:?}:\n  {}", id, msg)
  43                 }
  44                 let doc = block.contents.join("\n");
  45                 let location = Location::new(path.clone(), block.line);
  46                 acc.push(Feature { id, location, doc })
  47             }
  48
  49             Ok(())
  50         }
  51     }
  52 }
  53
  54 fn is_valid_feature_name(feature: &str) -> Result<(), String> {
  55     'word: for word in feature.split_whitespace() {
  56         for &short in ["to", "and"].iter() {
  57             if word == short {
  58                 continue 'word;
  59             }
  60         }
  61         for &short in ["To", "And"].iter() {
  62             if word == short {
  63                 return Err(format!("Don't capitalize {:?}", word));
  64             }
  65         }
  66         if !word.starts_with(char::is_uppercase) {
  67             return Err(format!("Capitalize {:?}", word));
  68         }
  69     }
  70     Ok(())
  71 }
  72
  73 impl fmt::Display for Feature {
  74     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  75         writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
  76     }
  77 }