huskies: merge 949

crates/source-map-gen/src/lib.rs

@@ -32,16 +32,34 @@ pub struct CheckFailure {
 }
 
 impl CheckFailure {
-    /// Returns a human-readable direction a coding agent can act on directly.
+    /// Returns a human-readable direction a coding agent can act on directly,
+    /// including a language-appropriate syntax example so the fix is in the error.
     pub fn to_direction(&self) -> String {
         format!(
-            "{}:{}: add a doc comment to {} `{}`",
+            "{}:{}: add a doc comment to {} `{}`. Example: {}",
             self.file_path.display(),
             self.line,
             self.item_kind,
-            self.item_name
+            self.item_name,
+            self.example_syntax(),
         )
     }
+
+    /// Concrete doc-comment syntax appropriate for this file's language.
+    fn example_syntax(&self) -> &'static str {
+        let ext = self
+            .file_path
+            .extension()
+            .and_then(|s| s.to_str())
+            .unwrap_or("");
+        let is_module_or_file = matches!(self.item_kind.as_str(), "module" | "file");
+        match ext {
+            "rs" if is_module_or_file => "`//! Brief description.` at the top of the file",
+            "rs" => "`/// Brief description.` above the declaration",
+            "ts" | "tsx" => "`/** Brief description. */` above the declaration",
+            _ => "(see project conventions for this file type)",
+        }
+    }
 }
 
 /// Result of a documentation coverage check.