From 3850b1faa2c55f250cfb91df0d8de70d3ed893bd Mon Sep 17 00:00:00 2001
From: Ross Sullivan <rosssullivan101@gmail.com>
Date: Sun, 25 May 2025 13:50:45 +0900
Subject: [PATCH] feat(unstable-book): Added unstable feature doc comments as
 feature descriptions

---
 src/tools/tidy/src/features.rs                | 17 ++++++++++++++
 src/tools/unstable-book-gen/src/main.rs       | 23 ++++++++++++++-----
 src/tools/unstable-book-gen/src/stub-issue.md |  2 ++
 .../unstable-book-gen/src/stub-no-issue.md    |  2 ++
 4 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/src/tools/tidy/src/features.rs b/src/tools/tidy/src/features.rs
index fcd7943e6e0a8..6093e7fd2632f 100644
--- a/src/tools/tidy/src/features.rs
+++ b/src/tools/tidy/src/features.rs
@@ -54,6 +54,7 @@ pub struct Feature {
     pub tracking_issue: Option<NonZeroU32>,
     pub file: PathBuf,
     pub line: usize,
+    pub description: Option<String>,
 }
 impl Feature {
     fn tracking_issue_display(&self) -> impl fmt::Display {
@@ -296,6 +297,7 @@ fn collect_lang_features_in(features: &mut Features, base: &Path, file: &str, ba
     let mut prev_names = vec![];
 
     let lines = contents.lines().zip(1..);
+    let mut doc_comments: Vec<String> = Vec::new();
     for (line, line_number) in lines {
         let line = line.trim();
 
@@ -332,6 +334,13 @@ fn collect_lang_features_in(features: &mut Features, base: &Path, file: &str, ba
             continue;
         }
 
+        if in_feature_group {
+            if let Some(doc_comment) = line.strip_prefix("///") {
+                doc_comments.push(doc_comment.trim().to_string());
+                continue;
+            }
+        }
+
         let mut parts = line.split(',');
         let level = match parts.next().map(|l| l.trim().trim_start_matches('(')) {
             Some("unstable") => Status::Unstable,
@@ -438,9 +447,15 @@ fn collect_lang_features_in(features: &mut Features, base: &Path, file: &str, ba
                     tracking_issue,
                     file: path.to_path_buf(),
                     line: line_number,
+                    description: if doc_comments.is_empty() {
+                        None
+                    } else {
+                        Some(doc_comments.join(" "))
+                    },
                 });
             }
         }
+        doc_comments.clear();
     }
 }
 
@@ -564,6 +579,7 @@ fn map_lib_features(
                         tracking_issue: find_attr_val(line, "issue").and_then(handle_issue_none),
                         file: file.to_path_buf(),
                         line: i + 1,
+                        description: None,
                     };
                     mf(Ok((feature_name, feature)), file, i + 1);
                     continue;
@@ -600,6 +616,7 @@ fn map_lib_features(
                     tracking_issue,
                     file: file.to_path_buf(),
                     line: i + 1,
+                    description: None,
                 };
                 if line.contains(']') {
                     mf(Ok((feature_name, feature)), file, i + 1);
diff --git a/src/tools/unstable-book-gen/src/main.rs b/src/tools/unstable-book-gen/src/main.rs
index 6cbdc83d5b5ff..3343577296005 100644
--- a/src/tools/unstable-book-gen/src/main.rs
+++ b/src/tools/unstable-book-gen/src/main.rs
@@ -12,13 +12,18 @@ use tidy::unstable_book::{
     collect_unstable_feature_names,
 };
 
-fn generate_stub_issue(path: &Path, name: &str, issue: u32) {
-    let content = format!(include_str!("stub-issue.md"), name = name, issue = issue);
+fn generate_stub_issue(path: &Path, name: &str, issue: u32, description: &str) {
+    let content = format!(
+        include_str!("stub-issue.md"),
+        name = name,
+        issue = issue,
+        description = description
+    );
     t!(write(path, content), path);
 }
 
-fn generate_stub_no_issue(path: &Path, name: &str) {
-    let content = format!(include_str!("stub-no-issue.md"), name = name);
+fn generate_stub_no_issue(path: &Path, name: &str, description: &str) {
+    let content = format!(include_str!("stub-no-issue.md"), name = name, description = description);
     t!(write(path, content), path);
 }
 
@@ -58,11 +63,17 @@ fn generate_unstable_book_files(src: &Path, out: &Path, features: &Features) {
         let file_name = format!("{feature_name}.md");
         let out_file_path = out.join(&file_name);
         let feature = &features[&feature_name_underscore];
+        let description = feature.description.as_deref().unwrap_or_default();
 
         if let Some(issue) = feature.tracking_issue {
-            generate_stub_issue(&out_file_path, &feature_name_underscore, issue.get());
+            generate_stub_issue(
+                &out_file_path,
+                &feature_name_underscore,
+                issue.get(),
+                &description,
+            );
         } else {
-            generate_stub_no_issue(&out_file_path, &feature_name_underscore);
+            generate_stub_no_issue(&out_file_path, &feature_name_underscore, &description);
         }
     }
 }
diff --git a/src/tools/unstable-book-gen/src/stub-issue.md b/src/tools/unstable-book-gen/src/stub-issue.md
index 8698fb7278f6a..f1e91b4ac172b 100644
--- a/src/tools/unstable-book-gen/src/stub-issue.md
+++ b/src/tools/unstable-book-gen/src/stub-issue.md
@@ -1,5 +1,7 @@
 # `{name}`
 
+{description}
+
 The tracking issue for this feature is: [#{issue}]
 
 [#{issue}]: https://github.com/rust-lang/rust/issues/{issue}
diff --git a/src/tools/unstable-book-gen/src/stub-no-issue.md b/src/tools/unstable-book-gen/src/stub-no-issue.md
index 3da140633d0f7..3674d0048aeb1 100644
--- a/src/tools/unstable-book-gen/src/stub-no-issue.md
+++ b/src/tools/unstable-book-gen/src/stub-no-issue.md
@@ -1,5 +1,7 @@
 # `{name}`
 
+{description}
+
 This feature has no tracking issue, and is therefore likely internal to the compiler, not being intended for general use.
 
 ------------------------