diff --git a/docs/plugins.md b/docs/plugins.md index d599cf544..5c1d754e4 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -163,6 +163,7 @@ export const printers = { canAttachComment, isBlockComment, printComment, + getCommentChildNodes, handleComments: { ownLine, endOfLine, @@ -297,6 +298,21 @@ Comments are often not part of a language's AST and present a challenge for pret By default, if the AST has a top-level `comments` property, Prettier assumes that `comments` stores an array of comment nodes. Prettier will then use the provided `parsers[].locStart`/`locEnd` functions to search for the AST node that each comment "belongs" to. Comments are then attached to these nodes **mutating the AST in the process**, and the `comments` property is deleted from the AST root. The `*Comment` functions are used to adjust Prettier's algorithm. Once the comments are attached to the AST, Prettier will automatically call the `printComment(path, options): Doc` function and insert the returned doc into the (hopefully) correct place. +#### (optional) `getCommentChildNodes` + +By default, Prettier searches all object properties (except for a few predefined ones) of each node recursively. This function can be provided to override that behavior. It has the signature: + +```ts +function getCommentChildNodes( + // The node whose children should be returned. + node: AST, + // Current options + options: object +): AST[] | undefined; +``` + +Return `[]` if the node has no children or `undefined` to fall back on the default behavior. + #### (optional) `printComment` Called whenever a comment node needs to be printed. It has the signature: