Skip to content

Commit 7d433e7

Browse files
cushongoogle-java-format Team
authored andcommitted
Update the class Javadoc on Formatter to reflect the current layout pipeline.
`Formatter` now builds a Wadler-style `layout.Doc` via `LayoutBuilder` and lays it out with `LayoutSolver` rather than using the `OpsBuilder`/`DocBuilder` pipeline, and it fails formatting on token mismatches instead of inserting missing input tokens. Also drop "new" from the opening sentence. PiperOrigin-RevId: 1004613453
1 parent 482d63d commit 7d433e7

1 file changed

Lines changed: 15 additions & 14 deletions

File tree

‎core/src/main/java/com/google/googlejavaformat/java/Formatter.java‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,9 @@
2424
import com.google.common.io.CharSource;
2525
import com.google.errorprone.annotations.Immutable;
2626
import com.google.googlejavaformat.CommentsHelper;
27-
import com.google.googlejavaformat.Doc;
2827
import com.google.googlejavaformat.FormattingError;
2928
import com.google.googlejavaformat.Newlines;
30-
import com.google.googlejavaformat.Op;
29+
import com.google.googlejavaformat.layout.Doc;
3130
import com.google.googlejavaformat.layout.LayoutBuilder;
3231
import com.google.googlejavaformat.layout.LayoutSolver;
3332
import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;
@@ -40,7 +39,7 @@
4039
import javax.tools.JavaFileObject;
4140
import org.jspecify.annotations.Nullable;
4241

43-
/// This is google-java-format, a new Java formatter that follows the Google Java Style Guide quite
42+
/// This is google-java-format, a Java formatter that follows the Google Java Style Guide quite
4443
/// precisely---to the letter and to the spirit.
4544
///
4645
/// This formatter uses the javac parser to generate an AST. Because the AST loses information about
@@ -51,24 +50,26 @@
5150
/// following a token on the same line go with that token; those following go with the next token---
5251
/// and there is a final EOF token to hold final comments.
5352
///
54-
/// The formatter walks the AST to generate a Greg Nelson/Derek Oppen-style list of formatting [Op]s
55-
/// [1--2] that then generates a structured [Doc]. Each AST node type has a visitor to emit a
56-
/// sequence of [Op]s for the node.
57-
///
58-
/// Some data-structure operations are easier in the list of [Op]s, while others become easier in
59-
/// the [Doc]. The [Op]s are walked to attach the comments. As the [Op]s are generated, missing
60-
/// input tokens are inserted and incorrect output tokens are dropped, ensuring that the output
61-
/// matches the input even in the face of formatter errors. Finally, the formatter walks the [Doc]
62-
/// to format it in the given width.
53+
/// The formatter walks the AST with [JavaInputAstVisitor] to emit formatting events to a
54+
/// [LayoutBuilder], which splices in comments from the token stream and builds a structured
55+
/// Wadler-style [Doc] \[1] using formatting rules adapted from Greg Nelson and Derek Oppen \[2--3].
56+
/// As the AST is walked, guessed optional tokens that are absent from the input are dropped, and
57+
/// any mismatch between the tokens emitted by the visitor and the input token stream fails
58+
/// formatting, ensuring that the output matches the input tokens. Finally, [LayoutSolver] lays out
59+
/// the [Doc] in the given width.
6360
///
6461
/// This formatter also produces data structures of which tokens and comments appear where on the
6562
/// input, and on the output, to help output a partial reformatting of a slightly edited input.
6663
///
6764
/// Instances of the formatter are immutable and thread-safe.
6865
///
69-
/// [1] Nelson, Greg, and John DeTreville. Personal communication.
66+
/// [1] Wadler, Philip. ["A prettier
67+
/// printer"](https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf). The Fun of
68+
/// Programming, Palgrave Macmillan, 2003, pp. 223–243.
69+
///
70+
/// [2] Nelson, Greg, and John DeTreville. Personal communication.
7071
///
71-
/// [2] Oppen, Derek C. "Prettyprinting". ACM Transactions on Programming Languages and Systems,
72+
/// [3] Oppen, Derek C. "Prettyprinting". ACM Transactions on Programming Languages and Systems,
7273
/// Volume 2 Issue 4, Oct. 1980, pp. 465–483.
7374
@Immutable
7475
public final class Formatter {

0 commit comments

Comments
 (0)