|
24 | 24 | import com.google.common.io.CharSource; |
25 | 25 | import com.google.errorprone.annotations.Immutable; |
26 | 26 | import com.google.googlejavaformat.CommentsHelper; |
27 | | -import com.google.googlejavaformat.Doc; |
28 | 27 | import com.google.googlejavaformat.FormattingError; |
29 | 28 | import com.google.googlejavaformat.Newlines; |
30 | | -import com.google.googlejavaformat.Op; |
| 29 | +import com.google.googlejavaformat.layout.Doc; |
31 | 30 | import com.google.googlejavaformat.layout.LayoutBuilder; |
32 | 31 | import com.google.googlejavaformat.layout.LayoutSolver; |
33 | 32 | import com.sun.tools.javac.tree.JCTree.JCCompilationUnit; |
|
40 | 39 | import javax.tools.JavaFileObject; |
41 | 40 | import org.jspecify.annotations.Nullable; |
42 | 41 |
|
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 |
44 | 43 | /// precisely---to the letter and to the spirit. |
45 | 44 | /// |
46 | 45 | /// This formatter uses the javac parser to generate an AST. Because the AST loses information about |
|
51 | 50 | /// following a token on the same line go with that token; those following go with the next token--- |
52 | 51 | /// and there is a final EOF token to hold final comments. |
53 | 52 | /// |
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. |
63 | 60 | /// |
64 | 61 | /// This formatter also produces data structures of which tokens and comments appear where on the |
65 | 62 | /// input, and on the output, to help output a partial reformatting of a slightly edited input. |
66 | 63 | /// |
67 | 64 | /// Instances of the formatter are immutable and thread-safe. |
68 | 65 | /// |
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. |
70 | 71 | /// |
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, |
72 | 73 | /// Volume 2 Issue 4, Oct. 1980, pp. 465–483. |
73 | 74 | @Immutable |
74 | 75 | public final class Formatter { |
|
0 commit comments