Encourage namespace import from prettier (#17928)

Co-authored-by: fisker Cheung <lionkay@gmail.com>

docs/plugins.md

@@ -184,9 +184,9 @@ export const printers = {
 Prettier uses an intermediate representation, called a Doc, which Prettier then turns into a string (based on options like `printWidth`). A _printer_'s job is to take the AST generated by `parsers[<parser name>].parse` and return a Doc. A Doc is constructed using [builder commands](https://github.com/prettier/prettier/blob/main/commands.md):
 
 ```js
-import { doc } from "prettier";
+import * as prettier from "prettier";
 
-const { join, line, ifBreak, group } = doc.builders;
+const { join, line, ifBreak, group } = prettier.doc.builders;
 ```
 
 The printing process consists of the following steps:
@@ -221,9 +221,9 @@ The `print` function is passed the following parameters:
 Here’s a simplified example to give an idea of what a typical implementation of `print` looks like:
 
 ```js
-import { doc } from "prettier";
+import * as prettier from "prettier";
 
-const { group, indent, join, line, softline } = doc.builders;
+const { group, indent, join, line, softline } = prettier.doc.builders;
 
 function print(path, options, print) {
   const node = path.node;
@@ -460,15 +460,15 @@ At the time of dispatching, Prettier will have annotated each AST comment node (
 
 #### Manually attaching a comment
 
-The `util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like:
+The `prettier.util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like:
 
 ```js
-import { util } from "prettier";
+import * as prettier from "prettier";
 
 function ownLine(comment, text, options, ast, isLastComment) {
   const { precedingNode } = comment;
   if (precedingNode && precedingNode.type === "punctuation") {
-    util.addTrailingComment(precedingNode, comment);
+    prettier.util.addTrailingComment(precedingNode, comment);
     return true;
   }
   return false;
@@ -479,7 +479,7 @@ Nodes with comments are expected to have a `comments` property containing an arr
 
 <!-- TODO: add a note that this might change in the future -->
 
-The example above uses `util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array.
+The example above uses `prettier.util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array.
 
 The `--debug-print-comments` CLI flag can help with debugging comment attachment issues. It prints a detailed list of comments, which includes information on how every comment was classified (`ownLine`/`endOfLine`/`remaining`, `leading`/`trailing`/`dangling`) and to which node it was attached. For Prettier’s built-in languages, this information is also available on the Playground (the 'show comments' checkbox in the Debug section).
 
@@ -638,10 +638,11 @@ Since plugins can be resolved using relative paths, when working on one you can
 
 ```js
 import * as prettier from "prettier";
+
 const code = "(add 1 2)";
 await prettier.format(code, {
   parser: "lisp",
-  plugins: ["."],
+  plugins: ["./index.js"],
 });
 ```
 

website/versioned_docs/version-stable/plugins.md

@@ -183,9 +183,9 @@ export const printers = {
 Prettier uses an intermediate representation, called a Doc, which Prettier then turns into a string (based on options like `printWidth`). A _printer_'s job is to take the AST generated by `parsers[<parser name>].parse` and return a Doc. A Doc is constructed using [builder commands](https://github.com/prettier/prettier/blob/main/commands.md):
 
 ```js
-import { doc } from "prettier";
+import * as prettier from "prettier";
 
-const { join, line, ifBreak, group } = doc.builders;
+const { join, line, ifBreak, group } = prettier.doc.builders;
 ```
 
 The printing process consists of the following steps:
@@ -220,9 +220,9 @@ The `print` function is passed the following parameters:
 Here’s a simplified example to give an idea of what a typical implementation of `print` looks like:
 
 ```js
-import { doc } from "prettier";
+import * as prettier from "prettier";
 
-const { group, indent, join, line, softline } = doc.builders;
+const { group, indent, join, line, softline } = prettier.doc.builders;
 
 function print(path, options, print) {
   const node = path.node;
@@ -459,15 +459,15 @@ At the time of dispatching, Prettier will have annotated each AST comment node (
 
 #### Manually attaching a comment
 
-The `util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like:
+The `prettier.util.addTrailingComment`/`addLeadingComment`/`addDanglingComment` functions can be used to manually attach a comment to an AST node. An example `ownLine` function that ensures a comment does not follow a "punctuation" node (made up for demonstration purposes) might look like:
 
 ```js
-import { util } from "prettier";
+import * as prettier from "prettier";
 
 function ownLine(comment, text, options, ast, isLastComment) {
   const { precedingNode } = comment;
   if (precedingNode && precedingNode.type === "punctuation") {
-    util.addTrailingComment(precedingNode, comment);
+    prettier.util.addTrailingComment(precedingNode, comment);
     return true;
   }
   return false;
@@ -478,7 +478,7 @@ Nodes with comments are expected to have a `comments` property containing an arr
 
 <!-- TODO: add a note that this might change in the future -->
 
-The example above uses `util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array.
+The example above uses `prettier.util.addTrailingComment`, which automatically sets `comment.leading`/`trailing`/`printed` to appropriate values and adds the comment to the AST node's `comments` array.
 
 The `--debug-print-comments` CLI flag can help with debugging comment attachment issues. It prints a detailed list of comments, which includes information on how every comment was classified (`ownLine`/`endOfLine`/`remaining`, `leading`/`trailing`/`dangling`) and to which node it was attached. For Prettier’s built-in languages, this information is also available on the Playground (the 'show comments' checkbox in the Debug section).
 
@@ -517,7 +517,7 @@ export default {
 
 ### Utility functions
 
-A `util` module from Prettier core is considered a private API and is not meant to be consumed by plugins. Instead, the `util-shared` module provides the following limited set of utility functions for plugins:
+`prettier.util` provides the following limited set of utility functions for plugins:
 
 ```ts
 type Quote = '"' | "'";
@@ -637,10 +637,11 @@ Since plugins can be resolved using relative paths, when working on one you can
 
 ```js
 import * as prettier from "prettier";
+
 const code = "(add 1 2)";
 await prettier.format(code, {
   parser: "lisp",
-  plugins: ["."],
+  plugins: ["./index.js"],
 });
 ```