From ac997670b1d7fe32b6977289f8bb3975f7edfd8c Mon Sep 17 00:00:00 2001 From: Micha Reiser Date: Fri, 16 Sep 2022 14:23:36 +0200 Subject: [PATCH] Document Comments API --- crates/rome_formatter/src/comments.rs | 559 ++++++++++++++++-- crates/rome_formatter/src/comments/builder.rs | 57 +- crates/rome_formatter/src/lib.rs | 8 +- crates/rome_formatter/src/token.rs | 6 +- 4 files changed, 537 insertions(+), 93 deletions(-) diff --git a/crates/rome_formatter/src/comments.rs b/crates/rome_formatter/src/comments.rs index f022ae8bbee5..ea6dd93e3a15 100644 --- a/crates/rome_formatter/src/comments.rs +++ b/crates/rome_formatter/src/comments.rs @@ -1,3 +1,80 @@ +//! Types for extracting and representing comments of a syntax tree. +//! +//! Most programming languages support comments allowing programmers to document their programs. Comments are different from other syntaxes because programming languages allow comments in almost any position, giving programmers great flexibility on where they can write comments: +//! +//! ```ignore +//! /** +//! * Documentation comment +//! */ +//! async /* comment */ function Test () // line comment +//! {/*inline*/} +//! ``` +//! +//! However, this flexibility makes formatting comments challenging because: +//! * The formatter must consistently place comments so that re-formatting the output yields the same result and does not create invalid syntax (line comments). +//! * It is essential that formatters place comments close to the syntax the programmer intended to document. However, the lack of rules regarding where comments are allowed and what syntax they document requires the use of heuristics to infer the documented syntax. +//! +//! This module strikes a balance between placing comments as closely as possible to their source location and reducing the complexity of formatting comments. It does so by associating comments per node rather than a token. This greatly reduces the combinations of possible comment positions but turns out to be, in practice, sufficiently precise to keep comments close to their source location. +//! +//! ## Node comments +//! +//! Comments are associated per node but get further distinguished on their location related to that node: +//! +//! ### Leading Comments +//! +//! A comment at the start of a node +//! +//! ```ignore +//! // Leading comment of the statement +//! console.log("test"); +//! +//! [/* leading comment of identifier */ a ]; +//! ``` +//! +//! ### Dangling Comments +//! +//! A comment that is neither at the start nor the end of a node +//! +//! ```ignore +//! [/* in between the brackets */ ]; +//! async /* between keywords */ function Test () {} +//! ``` +//! +//! ### Trailing Comments +//! +//! A comment at the end of a node +//! +//! ```ignore +//! [a /* trailing comment of a */, b, c]; +//! [ +//! a // trailing comment of a +//! ] +//! ``` +//! +//! ## Limitations +//! Limiting the placement of comments to leading, dangling, or trailing node comments reduces complexity inside the formatter but means, that the formatter's possibility of where comments can be formatted depends on the AST structure. +//! +//! For example, the continue statement in JavaScript is defined as: +//! +//! ```ungram +//! JsContinueStatement = +//! 'continue' +//! (label: 'ident')? +//! ';'? +//! ``` +//! +//! but a programmer may decide to add a comment in front or after the label: +//! +//! ```ignore +//! continue /* comment 1 */ label; +//! continue label /* comment 2*/; /* trailing */ +//! ``` +//! +//! Because all children of the `continue` statement are tokens, it is only possible to make the comments leading, dangling, or trailing comments of the `continue` statement. But this results in a loss of information as the formatting code can no longer distinguish if a comment appeared before or after the label and, thus, has to format them the same way. +//! +//! This hasn't shown to be a significant limitation today but the infrastructure could be extended to support a `label` on [`SourceComment`] that allows to further categorise comments. +//! + mod builder; mod map; @@ -16,9 +93,7 @@ pub enum CommentKind { /// /// ## Examples /// - /// ### JavaScript: - /// - /// ```javascript + /// ```ignore /// a /* test */ /// ``` InlineBlock, @@ -27,8 +102,6 @@ pub enum CommentKind { /// /// ## Examples /// - /// ### JavaScript - /// /// ```javascript /// /* first line /// * more content on the second line @@ -40,9 +113,7 @@ pub enum CommentKind { /// /// ## Examples /// - /// ### JavaScript - /// - /// ```javascript + /// ```ignore /// a // test /// ``` Line, @@ -66,7 +137,7 @@ impl CommentKind { /// ## Examples /// /// ```rust - /// use rome_formatter::CommentKind; + /// use rome_formatter::comments::CommentKind; /// /// // Block and InlineBlock comments can appear inline /// assert!(CommentKind::Block.is_inline()); @@ -80,6 +151,7 @@ impl CommentKind { } } +/// A comment in the source document. #[derive(Debug, Clone)] pub struct SourceComment { /// The number of lines appearing before this comment @@ -90,6 +162,7 @@ pub struct SourceComment { /// The comment piece pub(crate) piece: SyntaxTriviaPieceComments, + /// The kind of the comment. pub(crate) kind: CommentKind, } @@ -99,11 +172,53 @@ impl SourceComment { &self.piece } - /// Returns the number of lines before directly before this comment + /// The number of lines between this comment and the **previous** token or comment. + /// + /// # Examples + /// + /// ## Same line + /// + /// ```ignore + /// a // end of line + /// ``` + /// + /// Returns `0` because there's no line break between the token `a` and the comment. + /// + /// ## Own Line + /// + /// ```ignore + /// a; + /// + /// /* comment */ + /// ``` + /// + /// Returns `2` because there are two line breaks between the token `a` and the comment. pub fn lines_before(&self) -> u32 { self.lines_before } + /// The number of line breaks right after this comment. + /// + /// # Examples + /// + /// ## End of line + /// + /// ```ignore + /// a; // comment + /// + /// b; + /// ``` + /// + /// Returns `2` because there are two line breaks between the comment and the token `b`. + /// + /// ## Same line + /// + /// ```ignore + /// a; + /// /* comment */ b; + /// ``` + /// + /// Returns `0` because there are no line breaks between the comment and the token `b`. pub fn lines_after(&self) -> u32 { self.lines_after } @@ -114,13 +229,16 @@ impl SourceComment { } } +/// A comment decorated with additional information about its surrounding context in the source document. +/// +/// Used by [CommentStyle::place_comment] to determine if this should become a [leading](self#leading-comments), [dangling](self#dangling-comments), or [trailing](self#trailing-comments) comment. #[derive(Debug, Clone)] pub struct DecoratedComment { enclosing: SyntaxNode, preceding: Option>, following: Option>, following_token: SyntaxToken, - position: CommentTextPosition, + text_position: CommentTextPosition, lines_before: u32, lines_after: u32, comment: SyntaxTriviaPieceComments, @@ -128,53 +246,194 @@ pub struct DecoratedComment { } impl DecoratedComment { - /// The node that fully encloses the comment (the comment's start and end position are fully in the - /// node's bounds). + /// The closest parent node that fully encloses the comment. + /// + /// A node encloses a comment when the comment is between two of its direct children (ignoring lists). + /// + /// # Examples + /// + /// ```ignore + /// [a, /* comment */ b] + /// ``` + /// + /// The enclosing node is the array expression and not the identifier `b` because + /// `a` and `b` are children of the array expression and `comment` is a comment between the two nodes. pub fn enclosing_node(&self) -> &SyntaxNode { &self.enclosing } + /// Returns the comment piece. pub fn piece(&self) -> &SyntaxTriviaPieceComments { &self.comment } - /// The node directly preceding the comment or [None] if the comment is preceded by a token or is the first - /// token in the program. + /// Returns the node preceding the comment. + /// + /// The direct child node (ignoring lists) of the [`enclosing_node`](DecoratedComment::enclosing_node) that precedes this comment. + /// + /// Returns [None] if the [`enclosing_node`](DecoratedComment::enclosing_node) only consists of tokens or if + /// all preceding children of the [`enclosing_node`](DecoratedComment::enclosing_node) have been tokens. + /// + /// The Preceding node is guaranteed to be a sibling of [`following_node`](DecoratedComment::following_node). + /// + /// # Examples + /// + /// ## Preceding tokens only + /// + /// ```ignore + /// [/* comment */] + /// ``` + /// Returns [None] because the comment has no preceding node, only a preceding `[` token. + /// + /// ## Preceding node + /// + /// ```ignore + /// [a /* comment */, b] + /// ``` + /// + /// Returns `Some(a)` because `a` directly precedes the comment. + /// + /// ## Preceding token and node + /// + /// ```ignore + /// [a, /* comment */] + /// ``` + /// + /// Returns `Some(a)` because `a` is the preceding node of `comment`. The presence of the `,` token + /// doesn't change that. pub fn preceding_node(&self) -> Option<&SyntaxNode> { self.preceding.as_ref() } + /// Takes the [`preceding_node`](DecoratedComment::preceding_node) and replaces it with [None]. fn take_preceding_node(&mut self) -> Option> { self.preceding.take() } - /// The node directly following the comment or [None] if the comment is followed by a token or is the last token in the program. + /// Returns the node following the comment. + /// + /// The direct child node (ignoring lists) of the [`enclosing_node`](DecoratedComment::enclosing_node) that follows this comment. + /// + /// Returns [None] if the [`enclosing_node`](DecoratedComment::enclosing_node) only consists of tokens or if + /// all children children of the [`enclosing_node`](DecoratedComment::enclosing_node) following this comment are tokens. + /// + /// The following node is guaranteed to be a sibling of [`preceding_node`](DecoratedComment::preceding_node). + /// + /// # Examples + /// + /// ## Following tokens only + /// + /// ```ignore + /// [ /* comment */ ] + /// ``` + /// + /// Returns [None] because there's no node following the comment, only the `]` token. + /// + /// ## Following node + /// + /// ```ignore + /// [ /* comment */ a ] + /// ``` + /// + /// Returns `Some(a)` because `a` is the node directly following the comment. + /// + /// ## Following token and node + /// + /// ```ignore + /// async /* comment */ function test() {} + /// ``` + /// + /// Returns `Some(test)` because the `test` identifier is the first node following `comment`. + /// + /// ## Following parenthesized expression + /// + /// ```ignore + /// !( + /// a /* comment */ + /// ); + /// b + /// ``` + /// + /// Returns `None` because `comment` is enclosed inside the parenthesized expression and it has no children + /// following `/* comment */. pub fn following_node(&self) -> Option<&SyntaxNode> { self.following.as_ref() } + /// Takes the [`following_node`](DecoratedComment::following_node) and replaces it with [None]. fn take_following_node(&mut self) -> Option> { self.following.take() } - /// The number of lines between this comment and the **previous** token, comment or skipped trivia. + /// The number of lines between this comment and the **previous** token or comment. + /// + /// # Examples + /// + /// ## Same line + /// + /// ```ignore + /// a // end of line + /// ``` + /// + /// Returns `0` because there's no line break between the token `a` and the comment. + /// + /// ## Own Line + /// + /// ```ignore + /// a; + /// + /// /* comment */ + /// ``` + /// + /// Returns `2` because there are two line breaks between the token `a` and the comment. pub fn lines_before(&self) -> u32 { self.lines_before } + /// The number of line breaks right after this comment. + /// + /// # Examples + /// + /// ## End of line + /// + /// ```ignore + /// a; // comment + /// + /// b; + /// ``` + /// + /// Returns `2` because there are two line breaks between the comment and the token `b`. + /// + /// ## Same line + /// + /// ```ignore + /// a; + /// /* comment */ b; + /// ``` + /// + /// Returns `0` because there are no line breaks between the comment and the token `b`. pub fn lines_after(&self) -> u32 { self.lines_after } - /// Returns the [kind](CommentKind) of the comment. + /// Returns the [CommentKind] of the comment. pub fn kind(&self) -> CommentKind { self.kind } - pub fn position(&self) -> CommentTextPosition { - self.position + /// The position of the comment in the text. + pub fn text_position(&self) -> CommentTextPosition { + self.text_position } + /// The next token that comes after this comment. It is possible that other comments are between this comment + /// and the token. + /// + /// ```ignore + /// a /* comment */ /* other b */ + /// ``` + /// + /// The `following_token` for both comments is `b` because it's the token coming after the comments. pub fn following_token(&self) -> &SyntaxToken { &self.following_token } @@ -191,28 +450,53 @@ impl From> for SourceComment { } } -/// The position of a comment in the source document. +/// The position of a comment in the source text. #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub enum CommentTextPosition { - /// A comment that is separated by at least one line break from the following token + /// A comment that is on the same line as the preceding token and is separated by at least one line break from the following token. /// - /// ```javascript + /// # Examples + /// + /// ## End of line + /// + /// ```ignore /// a; /* this */ // or this /// b; + /// ``` + /// + /// Both `/* this */` and `// or this` are end of line comments because both comments are separated by + /// at least one line break from the following token `b`. + /// + /// ## Own line + /// + /// ```ignore + /// a; + /// /* comment */ + /// b; + /// ``` + /// + /// This is not an end of line comment because it isn't on the same line as the preceding token `a`. EndOfLine, - /// A Comment that is separated by at least one line break from the preceding token + /// A Comment that is separated by at least one line break from the preceding token. /// - /// ```javascript + /// # Examples + /// + /// ```ignore /// a; /// /* comment */ /* or this */ /// b; /// ``` + /// + /// Both comments are own line comments because they are separated by one line break from the preceding + /// token `a`. OwnLine, /// A comment that is placed on the same line as the preceding and following token. /// - /// ```javascript + /// # Examples + /// + /// ```ignore /// a /* comment */ + b /// ``` SameLine, @@ -234,29 +518,190 @@ impl CommentTextPosition { #[derive(Debug)] pub enum CommentPlacement { - /// Overrides the positioning of the comment to be a leading node comment. + /// Makes `comment` a [leading comment](self#leading-comments) of `node`. Leading { node: SyntaxNode, comment: SourceComment, }, - /// Overrides the positioning of the comment to be a trailing node comment. + /// Makes `comment` a [trailing comment](self#trailing-comments) of `node`. Trailing { node: SyntaxNode, comment: SourceComment, }, - /// Makes this comment a dangling comment of `node` + /// Makes `comment` a [dangling comment](self#dangling-comments) of `node`. Dangling { node: SyntaxNode, comment: SourceComment, }, - /// Uses the default positioning rules for the comment. - /// TODO document rules + /// Uses the default heuristic to determine the placement of the comment. + /// + /// # Same line comments + /// + /// Makes the comment a... + /// + /// * [trailing comment] of the [`preceding_node`] if both the [`following_node`] and [`preceding_node`] are not [None] + /// and the comment and [`preceding_node`] are only separated by a space (there's no token between the comment and [`preceding_node`]). + /// * [leading comment] of the [`following_node`] if the [`following_node`] is not [None] + /// * [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] + /// * [dangling comment] of the [`enclosing_node`]. + /// + /// ## Examples + /// ### Comment with preceding and following nodes + /// + /// ```ignore + /// [ + /// a, // comment + /// b + /// ] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a`. + /// + /// ### Comment with preceding node only + /// + /// ```ignore + /// [ + /// a // comment + /// ] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a`. + /// + /// ### Comment with following node only + /// + /// ```ignore + /// [ // comment + /// b + /// ] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b`. + /// + /// ### Dangling comment + /// + /// ```ignore + /// [ // comment + /// ] + /// ``` + /// + /// The comment becomes a [dangling comment] of the enclosing array expression because both the [`preceding_node`] and [`following_node`] are [None]. + /// + /// # Own line comments + /// + /// Makes the comment a... + /// + /// * [leading comment] of the [`following_node`] if the [`following_node`] is not [None] + /// * or a [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] + /// * or a [dangling comment] of the [`enclosing_node`]. + /// + /// ## Examples + /// + /// ### Comment with leading and preceding nodes + /// + /// ```ignore + /// [ + /// a, + /// // comment + /// b + /// ] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b`. + /// + /// ### Comment with preceding node only + /// + /// ```ignore + /// [ + /// a + /// // comment + /// ] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a`. + /// + /// ### Comment with following node only + /// + /// ```ignore + /// [ + /// // comment + /// b + /// ] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b`. + /// + /// ### Dangling comment + /// + /// ```ignore + /// [ + /// // comment + /// ] + /// ``` + /// + /// The comment becomes a [dangling comment] of the array expression because both [`preceding_node`] and [`following_node`] are [None]. + /// + /// + /// # End of line comments + /// Makes the comment a... + /// + /// * [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] + /// * or a [leading comment] of the [`following_node`] if the [`following_node`] is not [None] + /// * or a [dangling comment] of the [`enclosing_node`]. + /// + /// + /// ## Examples + /// + /// ### Comment with leading and preceding nodes + /// + /// ```ignore + /// [a /* comment */, b] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a` because there's no token between the node `a` and the `comment`. + /// + /// ```ignore + /// [a, /* comment */ b] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b` because the node `a` and the comment are separated by a `,` token. + /// + /// ### Comment with preceding node only + /// + /// ```ignore + /// [a, /* last */ ] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a` because the [`following_node`] is [None]. + /// + /// ### Comment with following node only + /// + /// ```ignore + /// [/* comment */ b] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b` because the [`preceding_node`] is [None] + /// + /// ### Dangling comment + /// + /// ```ignore + /// [/* comment*/] + /// ``` + /// + /// The comment becomes a [dangling comment] of the array expression because both [`preceding_node`] and [`following_node`] are [None]. + /// + /// [`preceding_node`]: DecoratedComment::preceding_node + /// [`following_node`]: DecoratedComment::following_node + /// [`enclosing_node`]: DecoratedComment::enclosing_node + /// [trailing comment]: self#trailing-comments + /// [leading comment]: self#leading-comments + /// [dangling comment]: self#dangling-comments Default(DecoratedComment), } impl CommentPlacement { + /// Makes `comment` a [leading comment](self#leading-comments) of `node`. #[inline] pub fn leading(node: SyntaxNode, comment: impl Into>) -> Self { Self::Leading { @@ -265,6 +710,7 @@ impl CommentPlacement { } } + /// Makes `comment` a [dangling comment](self::dangling-comments) of `node`. pub fn dangling(node: SyntaxNode, comment: impl Into>) -> Self { Self::Dangling { node, @@ -272,6 +718,7 @@ impl CommentPlacement { } } + /// Makes `comment` a [trailing comment](self::trailing-comments) of `node`. #[inline] pub fn trailing(node: SyntaxNode, comment: impl Into>) -> Self { Self::Trailing { @@ -280,13 +727,14 @@ impl CommentPlacement { } } + /// Returns the placement if it isn't [CommentPlacement::Default], otherwise calls `f` and returns the result. #[inline] - pub fn or_else(self, or_else: F) -> Self + pub fn or_else(self, f: F) -> Self where F: FnOnce(DecoratedComment) -> CommentPlacement, { match self { - CommentPlacement::Default(comment) => or_else(comment), + CommentPlacement::Default(comment) => f(comment), placement => placement, } } @@ -304,6 +752,9 @@ pub trait CommentStyle: Default { /// Returns the (kind)[CommentKind] of the comment fn get_comment_kind(comment: &SyntaxTriviaPieceComments) -> CommentKind; + /// Determines the placement of `comment`. + /// + /// The default implementation returns [CommentPlacement::Default]. fn place_comment( &self, comment: DecoratedComment, @@ -312,11 +763,7 @@ pub trait CommentStyle: Default { } } -/// Type that stores the comments of a tree and gives access to: -/// -/// * whether a node should be formatted as is because it has a leading suppression comment. -/// * a node's leading and trailing comments -/// * the dangling comments of a token +/// The comments of a syntax tree stored by node. /// /// Cloning `comments` is cheap as it only involves bumping a reference counter. #[derive(Debug, Clone, Default)] @@ -340,7 +787,7 @@ pub struct Comments { } impl Comments { - /// Extracts all the suppressions from `root` and its child nodes. + /// Extracts all the comments from `root` and its descendants nodes. pub fn from_node