feat(codegen): print jsdoc comments that are attached to statements a…

…nd class elements (#5845)

I am unable to print all comments correctly. Comments have way too much semantic meaning in JavaScript.

This PR reduces the scope to only print jsdoc comments that are attached to statements and class elements, in order to get isolated declarations shipped.

crates/oxc_ast/src/trivia.rs

@@ -104,6 +104,10 @@ impl Comment {
     pub fn real_span_start(&self) -> u32 {
         self.span.start - 2
     }
+
+    pub fn is_jsdoc(&self, source_text: &str) -> bool {
+        self.is_leading() && self.is_block() && self.span.source_text(source_text).starts_with('*')
+    }
 }
 
 /// Sorted set of unique trivia comments, in ascending order by starting position.

crates/oxc_codegen/src/comment.rs

@@ -0,0 +1,74 @@
+use oxc_syntax::identifier::is_line_terminator;
+use rustc_hash::FxHashMap;
+
+use oxc_ast::{Comment, CommentKind, Trivias};
+
+use crate::Codegen;
+
+pub type CommentsMap = FxHashMap</* attached_to */ u32, Vec<Comment>>;
+
+impl<'a> Codegen<'a> {
+    pub(crate) fn build_leading_comments(&mut self, source_text: &str, trivias: &Trivias) {
+        let mut leading_comments: CommentsMap = FxHashMap::default();
+        for comment in trivias
+            .comments()
+            .copied()
+            .filter(|comment| Self::should_keep_comment(comment, source_text))
+        {
+            leading_comments.entry(comment.attached_to).or_default().push(comment);
+        }
+        self.leading_comments = leading_comments;
+    }
+
+    fn should_keep_comment(comment: &Comment, source_text: &str) -> bool {
+        comment.is_jsdoc(source_text)
+            && comment.preceded_by_newline
+            // webpack comment `/*****/`
+            && !comment.span.source_text(source_text).chars().all(|c| c == '*')
+    }
+
+    pub(crate) fn print_leading_comments(&mut self, start: u32) {
+        if self.options.minify {
+            return;
+        }
+        let Some(source_text) = self.source_text else { return };
+        let Some(comments) = self.leading_comments.remove(&start) else { return };
+
+        let first = comments.first().unwrap();
+        if first.preceded_by_newline {
+            // Skip printing newline if this comment is already on a newline.
+            if self.peek_nth(0).is_some_and(|c| c != '\n' && c != '\t') {
+                self.print_char(b'\n');
+                self.print_indent();
+            }
+        }
+
+        for comment in &comments {
+            let s = comment.real_span().source_text(source_text);
+            match comment.kind {
+                CommentKind::Line => {
+                    self.print_str(s);
+                }
+                CommentKind::Block => {
+                    // Print block comments with our own indentation.
+                    let lines = s.split(is_line_terminator);
+                    for line in lines {
+                        if !line.starts_with("/*") {
+                            self.print_indent();
+                        }
+                        self.print_str(line.trim_start());
+                        if !line.ends_with("*/") {
+                            self.print_hard_newline();
+                        }
+                    }
+                }
+            }
+        }
+
+        let last = comments.last().unwrap();
+        if last.is_line() || last.followed_by_newline {
+            self.print_hard_newline();
+            self.print_indent();
+        }
+    }
+}

crates/oxc_codegen/src/gen.rs

@@ -73,6 +73,7 @@ impl<'a> Gen for Directive<'a> {
 
 impl<'a> Gen for Statement<'a> {
     fn gen(&self, p: &mut Codegen, ctx: Context) {
+        p.print_leading_comments(self.span().start);
         match self {
             Self::BlockStatement(stmt) => stmt.print(p, ctx),
             Self::BreakStatement(stmt) => stmt.print(p, ctx),
@@ -468,6 +469,7 @@ impl<'a> Gen for ReturnStatement<'a> {
     fn gen(&self, p: &mut Codegen, _ctx: Context) {
         p.add_source_mapping(self.span.start);
         p.print_indent();
+        p.print_space_before_identifier();
         p.print_str("return");
         if let Some(arg) = &self.argument {
             p.print_hard_space();
@@ -2204,22 +2206,27 @@ impl<'a> Gen for ClassElement<'a> {
     fn gen(&self, p: &mut Codegen, ctx: Context) {
         match self {
             Self::StaticBlock(elem) => {
+                p.print_leading_comments(elem.span.start);
                 elem.print(p, ctx);
                 p.print_soft_newline();
             }
             Self::MethodDefinition(elem) => {
+                p.print_leading_comments(elem.span.start);
                 elem.print(p, ctx);
                 p.print_soft_newline();
             }
             Self::PropertyDefinition(elem) => {
+                p.print_leading_comments(elem.span.start);
                 elem.print(p, ctx);
                 p.print_semicolon_after_statement();
             }
             Self::AccessorProperty(elem) => {
+                p.print_leading_comments(elem.span.start);
                 elem.print(p, ctx);
                 p.print_semicolon_after_statement();
             }
             Self::TSIndexSignature(elem) => {
+                p.print_leading_comments(elem.span.start);
                 elem.print(p, ctx);
                 p.print_semicolon_after_statement();
             }

crates/oxc_codegen/src/lib.rs

@@ -5,6 +5,7 @@
 
 mod annotation_comment;
 mod binary_expr_visitor;
+mod comment;
 mod context;
 mod gen;
 mod operator;
@@ -25,10 +26,9 @@ use oxc_syntax::{
 };
 use rustc_hash::FxHashMap;
 
-use self::annotation_comment::AnnotationComment;
 use crate::{
-    binary_expr_visitor::BinaryExpressionVisitor, operator::Operator,
-    sourcemap_builder::SourcemapBuilder,
+    annotation_comment::AnnotationComment, binary_expr_visitor::BinaryExpressionVisitor,
+    comment::CommentsMap, operator::Operator, sourcemap_builder::SourcemapBuilder,
 };
 pub use crate::{
     context::Context,
@@ -75,6 +75,7 @@ pub struct Codegen<'a> {
     source_text: Option<&'a str>,
 
     trivias: Trivias,
+    leading_comments: CommentsMap,
 
     mangler: Option<Mangler>,
 
@@ -142,6 +143,7 @@ impl<'a> Codegen<'a> {
             comment_options: CommentOptions::default(),
             source_text: None,
             trivias: Trivias::default(),
+            leading_comments: CommentsMap::default(),
             mangler: None,
             code: vec![],
             needs_semicolon: false,
@@ -200,6 +202,7 @@ impl<'a> Codegen<'a> {
         trivias: Trivias,
         options: CommentOptions,
     ) -> Self {
+        self.build_leading_comments(source_text, &trivias);
         self.trivias = trivias;
         self.comment_options = options;
         self.with_source_text(source_text)

crates/oxc_codegen/tests/integration/jsdoc.rs

@@ -0,0 +1,78 @@
+use crate::snapshot;
+
+#[test]
+fn comment() {
+    let cases = vec![
+        r"
+/** This is a description of the foo function. */
+function foo() {
+}
+
+/**
+ * Represents a book.
+ * @constructor
+ * @param {string} title - The title of the book.
+ * @param {string} author - The author of the book.
+ */
+function Book(title, author) {
+}
+
+/** Class representing a point. */
+class Point {
+    /**
+     * Create a point.
+     * @param {number} x - The x value.
+     * @param {number} y - The y value.
+     */
+    constructor(x, y) {
+    }
+
+    /**
+     * Get the x value.
+     * @return {number} The x value.
+     */
+    getX() {
+    }
+
+    /**
+     * Get the y value.
+     * @return {number} The y value.
+     */
+    getY() {
+    }
+
+    /**
+     * Convert a string containing two comma-separated numbers into a point.
+     * @param {string} str - The string containing two comma-separated numbers.
+     * @return {Point} A Point object.
+     */
+    static fromString(str) {
+    }
+}
+
+/** Class representing a point. */
+const Point = class {
+}
+
+/**
+ * Shirt module.
+ * @module my/shirt
+ */
+
+/** Button the shirt. */
+exports.button = function() {
+};
+
+/** Unbutton the shirt. */
+exports.unbutton = function() {
+};
+
+this.Book = function(title) {
+    /** The title of the book. */
+    this.title = title;
+}
+        ",
+    ];
+
+    snapshot("jsodc", &cases);
+}

crates/oxc_codegen/tests/integration/main.rs

@@ -1,5 +1,6 @@
 #![allow(clippy::missing_panics_doc)]
 pub mod esbuild;
+pub mod jsdoc;
 pub mod pure_comments;
 pub mod tester;
 pub mod ts;

crates/oxc_codegen/tests/integration/snapshots/jsodc.snap

@@ -0,0 +1,121 @@
+---
+source: crates/oxc_codegen/tests/integration/main.rs
+---
+########## 0
+
+/** This is a description of the foo function. */
+function foo() {
+}
+
+/**
+ * Represents a book.
+ * @constructor
+ * @param {string} title - The title of the book.
+ * @param {string} author - The author of the book.
+ */
+function Book(title, author) {
+}
+
+/** Class representing a point. */
+class Point {
+    /**
+     * Create a point.
+     * @param {number} x - The x value.
+     * @param {number} y - The y value.
+     */
+    constructor(x, y) {
+    }
+
+    /**
+     * Get the x value.
+     * @return {number} The x value.
+     */
+    getX() {
+    }
+
+    /**
+     * Get the y value.
+     * @return {number} The y value.
+     */
+    getY() {
+    }
+
+    /**
+     * Convert a string containing two comma-separated numbers into a point.
+     * @param {string} str - The string containing two comma-separated numbers.
+     * @return {Point} A Point object.
+     */
+    static fromString(str) {
+    }
+}
+
+/** Class representing a point. */
+const Point = class {
+}
+
+/**
+ * Shirt module.
+ * @module my/shirt
+ */
+
+/** Button the shirt. */
+exports.button = function() {
+};
+
+/** Unbutton the shirt. */
+exports.unbutton = function() {
+};
+
+this.Book = function(title) {
+    /** The title of the book. */
+    this.title = title;
+}
+
+----------
+/** This is a description of the foo function. */
+function foo() {}
+/**
+* Represents a book.
+* @constructor
+* @param {string} title - The title of the book.
+* @param {string} author - The author of the book.
+*/
+function Book(title, author) {}
+/** Class representing a point. */
+class Point {
+	/**
+	* Create a point.
+	* @param {number} x - The x value.
+	* @param {number} y - The y value.
+	*/
+	constructor(x, y) {}
+	/**
+	* Get the x value.
+	* @return {number} The x value.
+	*/
+	getX() {}
+	/**
+	* Get the y value.
+	* @return {number} The y value.
+	*/
+	getY() {}
+	/**
+	* Convert a string containing two comma-separated numbers into a point.
+	* @param {string} str - The string containing two comma-separated numbers.
+	* @return {Point} A Point object.
+	*/
+	static fromString(str) {}
+}
+/** Class representing a point. */
+const Point = class {};
+/**
+* Shirt module.
+* @module my/shirt
+*//** Button the shirt. */
+exports.button = function() {};
+/** Unbutton the shirt. */
+exports.unbutton = function() {};
+this.Book = function(title) {
+/** The title of the book. */
+		this.title = title;
+};