From c67ffd58c88a3e509668099c2d9a54ec635d4e1a Mon Sep 17 00:00:00 2001 From: David Gregory <2992938+DavidGregory084@users.noreply.github.com> Date: Fri, 31 May 2024 01:50:56 +0100 Subject: [PATCH] Update Javadoc to account for RenderOptions --- README.md | 14 +- build.gradle.kts | 21 ++ .../com/opencastsoftware/prettier4j/Doc.java | 303 ++++++++---------- .../prettier4j/RenderOptions.java | 49 ++- 4 files changed, 210 insertions(+), 177 deletions(-) diff --git a/README.md b/README.md index c065dc8..1266a68 100644 --- a/README.md +++ b/README.md @@ -36,22 +36,22 @@ To render documents using this library you must use [com.opencastsoftware.pretti In order to create documents, check out the static methods of that class, especially: -* [empty()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#empty--) - creates an empty `Doc`. -* [text(String)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#text-java.lang.String-) - creates a `Doc` from a `String`. These are used as the atomic text nodes of a document. +* [empty()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#empty()) - creates an empty `Doc`. +* [text(String)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#text(java.lang.String)) - creates a `Doc` from a `String`. These are used as the atomic text nodes of a document. -To render documents, the [render(int)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#render-int-) instance method is provided. The argument to this method declares a target line width when laying out the document. +To render documents, the [render(int)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#render(int)) instance method is provided. The argument to this method declares a target line width when laying out the document. It's not always possible for documents to fit within this target width. For example, a single `Doc.text` node may be longer than the target width if the argument `String` is long enough. -To concatenate documents, the [append(Doc)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#append-com.opencastsoftware.prettier4j.Doc-) instance method and related methods providing different separators are provided. +To concatenate documents, the [append(Doc)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#append(com.opencastsoftware.prettier4j.Doc)) instance method and related methods providing different separators are provided. As a general rule, the best way to construct documents using this algorithm is to construct your document by concatenating text nodes, while declaring each place where a line break could be added if necessary. The layout algorithm uses the concept of "flattened" layouts - layouts which are used when they are able to fit within the remaining space on the current line. In other words, they are "flattened" onto a single line. -The [lineOrSpace()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#lineOrSpace--), [lineOrEmpty()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#lineOrEmpty--) and related static methods are used to declare line breaks which may be replaced with alternative content if the current `Doc` is flattened. +The [lineOrSpace()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#lineOrSpace()), [lineOrEmpty()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#lineOrEmpty()) and related static methods are used to declare line breaks which may be replaced with alternative content if the current `Doc` is flattened. -The [line()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#line--) static method creates a line break which may not be flattened. +The [line()](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#line()) static method creates a line break which may not be flattened. However, none of these primitives create flattened layouts on their own. @@ -75,7 +75,7 @@ Doc.text("one") // ===> "one\ntwo\nthree" ``` -However, if we declare each of those documents as a group using the static method [group(Doc)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#group-com.opencastsoftware.prettier4j.Doc-), they are rendered differently: +However, if we declare each of those documents as a group using the static method [group(Doc)](https://www.javadoc.io/static/com.opencastsoftware/prettier4j/0.2.0/com/opencastsoftware/prettier4j/Doc.html#group(com.opencastsoftware.prettier4j.Doc)), they are rendered differently: ```java Doc.group( diff --git a/build.gradle.kts b/build.gradle.kts index 5dcff97..01e35fd 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -81,13 +81,22 @@ tasks.withType { tasks.withType { options { this as StandardJavadocDocletOptions + + addStringOption("-release", "8") + + // Only show overridden methods in summary section + addStringOption("-override-methods", "summary") + + // Syntax highlighting of snippets addBooleanOption("-allow-script-in-comments", true) + header( """ | """ .trimMargin() ) + footer( """ | @@ -95,6 +104,18 @@ tasks.withType { """ .trimMargin() ) + + // JDK documentation links: + // Unfortunately we can't link to JDK8 because JDK11 javadoc + // cannot handle missing element-list file + links("https://docs.oracle.com/en/java/javase/11/docs/api/") + + // Javadoc.io links + val compileClasspath by configurations.getting + val javadocIo = "https://www.javadoc.io/doc" + compileClasspath.allDependencies.forEach { + links("$javadocIo/${it.group}/${it.name}/${it.version}/") + } } } diff --git a/src/main/java/com/opencastsoftware/prettier4j/Doc.java b/src/main/java/com/opencastsoftware/prettier4j/Doc.java index f223b63..206c067 100644 --- a/src/main/java/com/opencastsoftware/prettier4j/Doc.java +++ b/src/main/java/com/opencastsoftware/prettier4j/Doc.java @@ -19,48 +19,44 @@ * Implements the algorithm described in Philip Wadler's "A prettier printer", a * pretty printing algorithm for laying out hierarchical documents as text. *

- * To construct a document, see the static methods of - * {@link com.opencastsoftware.prettier4j.Doc Doc}, especially - * {@link com.opencastsoftware.prettier4j.Doc#text(String) text}, - * {@link com.opencastsoftware.prettier4j.Doc#empty() empty}, - * {@link com.opencastsoftware.prettier4j.Doc#line() line} and its related - * methods. + * To construct a document, see the static methods of {@link Doc}, especially + * {@link Doc#text(String) text}, {@link Doc#empty() empty}, {@link Doc#line() line} + * and its related methods. *

- * To concatenate documents, see - * {@link com.opencastsoftware.prettier4j.Doc#append(Doc) append} and its - * related instance methods. + * To concatenate documents, see {@link Doc#append(Doc) append} and its related + * instance methods. *

* To declare groups of content which should be collapsed onto one line if - * possible, see the static method - * {@link com.opencastsoftware.prettier4j.Doc#group(Doc) group}. + * possible, see the static method {@link Doc#group(Doc) group}. *

* To style a {@link Doc} with ANSI escape codes, see the instance method * {@link Doc#styled(Styles.StylesOperator...)} or static method * {@link Doc#styled(Doc, Styles.StylesOperator...)}. *

- * To render documents to an {@link java.lang.Appendable Appendable} output, see the instance method + * To render documents to an {@link Appendable} output, see the instance method * {@link Doc#render(RenderOptions, Appendable)} or static method * {@link Doc#render(Doc, RenderOptions, Appendable)}. *

- * To render documents to {@link java.lang.String String}, see the instance method + * To render documents to {@link String}, see the instance method * {@link Doc#render(RenderOptions)} or static method * {@link Doc#render(Doc, RenderOptions)}. * - * @see A - * prettier printer + * @see + * A prettier printer + * */ public abstract class Doc { + private Doc() {} + /** - * Returns a flattened layout for the current - * {@link com.opencastsoftware.prettier4j.Doc Doc}. + * Returns a flattened layout for the current {@link Doc}. * * @return the flattened document. */ abstract Doc flatten(); /** - * Indicate whether the current {@link com.opencastsoftware.prettier4j.Doc Doc} + * Indicate whether the current {@link Doc} * contains any parameters. * * @return whether this {@link Doc} contains any parameters. @@ -74,7 +70,7 @@ public abstract class Doc { * @param value the value to use to replace the parameter placeholder. * @return this {@link Doc} with all instances of the named parameter replaced by {@code value}. */ - abstract Doc bind(String name, Doc value); + public abstract Doc bind(String name, Doc value); /** * Bind named parameters to the {@link Doc}s provided via {@code bindings}. @@ -82,7 +78,7 @@ public abstract class Doc { * @param bindings the bindings to use to replace named parameters. * @return this {@link Doc} with all matching named parameters replaced by their corresponding values. */ - abstract Doc bind(Map bindings); + public abstract Doc bind(Map bindings); /** * Bind named parameters to the name-to-{@link Doc} pairs provided via {@code bindings}. @@ -131,22 +127,20 @@ public Doc bind(String name, String value) { } /** - * Append the {@code other} {@link com.opencastsoftware.prettier4j.Doc Doc} to - * this one. + * Append the {@code other} {@link Doc} to this one. * * @param other the other document. - * @return the concatenated {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return the concatenated {@link Doc}. */ public Doc append(Doc other) { return new Append(this, other); } /** - * Append the {@code other} {@link com.opencastsoftware.prettier4j.Doc Doc} to - * this one, separated by a space character. + * Append the {@code other} {@link Doc} to this one, separated by a space character. * * @param other the other document. - * @return the concatenated {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return the concatenated {@link Doc}. */ public Doc appendSpace(Doc other) { return this @@ -155,11 +149,11 @@ public Doc appendSpace(Doc other) { } /** - * Append the {@code other} {@link com.opencastsoftware.prettier4j.Doc Doc} to - * this one, separated by a line break which cannot be flattened. + * Append the {@code other} {@link Doc} to this one, + * separated by a line break which cannot be flattened. * * @param other the other document. - * @return the concatenated {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return the concatenated {@link Doc}. */ public Doc appendLine(Doc other) { return this @@ -168,12 +162,11 @@ public Doc appendLine(Doc other) { } /** - * Append the {@code other} {@link com.opencastsoftware.prettier4j.Doc Doc} to - * this one, separated by a line break which may be flattened into a space - * character. + * Append the {@code other} {@link Doc Doc} to this one, separated by + * a line break which may be flattened into a space character. * * @param other the other document. - * @return the concatenated {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return the concatenated {@link Doc}. */ public Doc appendLineOrSpace(Doc other) { return this @@ -182,12 +175,11 @@ public Doc appendLineOrSpace(Doc other) { } /** - * Append the {@code other} {@link com.opencastsoftware.prettier4j.Doc Doc} to - * this one, separated by a line break which may be flattened into an empty - * document. + * Append the {@code other} {@link Doc} to this one, separated by + * a line break which may be flattened into an empty document. * * @param other the other document. - * @return the concatenated {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return the concatenated {@link Doc}. */ public Doc appendLineOrEmpty(Doc other) { return this @@ -196,28 +188,26 @@ public Doc appendLineOrEmpty(Doc other) { } /** - * Append the {@code other} {@link com.opencastsoftware.prettier4j.Doc Doc} to - * this one, separated by a line break which may be flattened into the - * {@code altText} String. + * Append the {@code other} {@link Doc} to this one, separated by + * a line break which may be flattened into the {@code altText} {@link String}. * * @param altText the alternative text to display if the line break is * flattened. * @param other the other document. - * @return the concatenated {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return the concatenated {@link Doc}. */ public Doc appendLineOr(String altText, Doc other) { return this.appendLineOr(text(altText), other); } /** - * Append the {@code other} {@link com.opencastsoftware.prettier4j.Doc Doc} to - * this one, separated by a line break which may be flattened into the - * {@code altDoc} document. + * Append the {@code other} {@link Doc} to this one, separated by + * a line break which may be flattened into the {@code altDoc} document. * * @param altDoc the alternative document to display if the line break is * flattened. * @param other the other document. - * @return the concatenated {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return the concatenated {@link Doc}. */ public Doc appendLineOr(Doc altDoc, Doc other) { return this @@ -226,8 +216,7 @@ public Doc appendLineOr(Doc altDoc, Doc other) { } /** - * Indent the current {@link com.opencastsoftware.prettier4j.Doc Doc} by - * {@code indent} spaces. + * Indent the current {@link Doc} by {@code indent} spaces. * * @param indent the number of spaces of indent to apply. * @return the indented document. @@ -302,11 +291,10 @@ public Doc bracket(int indent, Doc lineDoc, Doc left, Doc right) { } /** - * Styles the current {@link com.opencastsoftware.prettier4j.Doc Doc} using the styles - * provided via {@code styles}. + * Styles the current {@link Doc} using the styles provided via {@code styles}. * * @param styles the styles to use to decorate the input {@code doc}. - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} decorated with the ANSI styles provided. + * @return a {@link Doc} decorated with the ANSI styles provided. * @see Styles * @see com.opencastsoftware.prettier4j.ansi.Color Color */ @@ -315,55 +303,51 @@ public final Doc styled(Styles.StylesOperator...styles) { } /** - * Renders the current {@link com.opencastsoftware.prettier4j.Doc Doc} into a - * {@link java.lang.String String}, aiming to lay out the document with at most - * {@code width} characters on each line. + * Renders the current {@link Doc} into a {@link String}, attempting to lay out the document + * according to the {@link RenderOptions#defaults() default} rendering options. * - * @return the document laid out as a {@link java.lang.String String}. + * @return the document laid out as a {@link String}. */ public String render() { return render(this); } /** - * Renders the current {@link com.opencastsoftware.prettier4j.Doc Doc} into a - * {@link java.lang.String String}, aiming to lay out the document with at most - * {@code width} characters on each line. + * Renders the current {@link Doc} into a {@link String}, attempting to lay out the document + * according to the rendering {@code options}. * * @param options the options to use for rendering. - * @return the document laid out as a {@link java.lang.String String}. + * @return the document laid out as a {@link String}. */ public String render(RenderOptions options) { return render(this, options); } /** - * Renders the current {@link com.opencastsoftware.prettier4j.Doc Doc} into a - * {@link java.lang.String String}, aiming to lay out the document with at most - * {@code width} characters on each line. + * Renders the current {@link Doc Doc} into an {@link Appendable}, attempting to lay out the document + * according to the {@link RenderOptions#defaults() default} rendering options. * - * @return the document laid out as a {@link java.lang.String String}. + * @param output the output to render into. + * @throws IOException if the {@link Appendable} {@code output} throws when {@link Appendable#append(CharSequence) append}ed. */ public void render(Appendable output) throws IOException { render(this, output); } /** - * Renders the current {@link com.opencastsoftware.prettier4j.Doc Doc} into a - * {@link java.lang.String String}, aiming to lay out the document with at most - * {@code width} characters on each line. + * Renders the current {@link Doc} into a {@link String}, attempting to lay out the document with at + * most {@code width} characters on each line. * * @param width the preferred maximum rendering width. - * @return the document laid out as a {@link java.lang.String String}. + * @return the document laid out as a {@link String}. */ public String render(int width) { return render(this, new RenderOptions(width, true)); } /** - * Renders the current {@link com.opencastsoftware.prettier4j.Doc Doc} into an - * {@link java.lang.Appendable Appendable}, aiming to lay out the document with at most - * {@code width} characters on each line. + * Renders the current {@link Doc} into an {@link Appendable}, attempting to lay out the document + * with at most {@code width} characters on each line. * * @param width the preferred maximum rendering width. * @param output the output to render into. @@ -374,9 +358,8 @@ public void render(int width, Appendable output) throws IOException { } /** - * Renders the current {@link com.opencastsoftware.prettier4j.Doc Doc} into an - * {@link java.lang.Appendable Appendable}, aiming to lay out the document with at most - * {@code width} characters on each line. + * Renders the current {@link Doc} into an {@link Appendable}, attempting to lay out the document + * according to the rendering {@code options}. * * @param options the options to use for rendering. * @param output the output to render into. @@ -411,12 +394,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return this; } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return this; } @@ -452,8 +435,7 @@ public String toString() { } /** - * Represents the concatenation of two - * {@link com.opencastsoftware.prettier4j.Doc Doc}s. + * Represents the concatenation of two {@link Doc}s. */ public static class Append extends Doc { private final Doc left; @@ -483,12 +465,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return new Append(left.bind(name, value), right.bind(name, value)); } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return new Append(left.bind(bindings), right.bind(bindings)); } @@ -531,23 +513,27 @@ public String toString() { /** * Represents a choice between a flattened and expanded layout for a - * single {@link com.opencastsoftware.prettier4j.Doc Doc}. + * single {@link Doc}. *

* We must maintain two invariants in constructing this class: * *

    - *
  • {@link com.opencastsoftware.prettier4j.Doc.Alternatives#left left} and - * {@link com.opencastsoftware.prettier4j.Doc.Alternatives#right right} must - * flatten to the same layout
    • - *
  • the first line of - * {@link com.opencastsoftware.prettier4j.Doc.Alternatives#left left} must not - * be shorter than the first line of - * {@link com.opencastsoftware.prettier4j.Doc.Alternatives#right right}
    • - *
* + *
  • + * {@link Doc.Alternatives#left() left} and {@link Doc.Alternatives#right() right} + * must flatten to the same layout. + *
    • + * + *
  • + * the first line of {@link Doc.Alternatives#left() left} must not be shorter + * than the first line of {@link Doc.Alternatives#right() right} + *
    • + * + * + *

    * As long as these invariants are preserved recursively, we know that we can * always choose the shorter layout for this document by choosing - * {@link com.opencastsoftware.prettier4j.Doc.Alternatives#right right}. + * {@link Alternatives#right() right}. */ public static class Alternatives extends Doc { private final Doc left; @@ -577,12 +563,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return new Alternatives(left.bind(name, value), right.bind(name, value)); } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return new Alternatives(left.bind(bindings), right.bind(bindings)); } @@ -624,7 +610,7 @@ public String toString() { } /** - * Represents an indented {@link com.opencastsoftware.prettier4j.Doc Doc}. + * Represents an indented {@link Doc}. */ public static class Indent extends Doc { private final int indent; @@ -654,12 +640,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return new Indent(indent, doc.bind(name, value)); } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return new Indent(indent, doc.bind(bindings)); } @@ -713,12 +699,12 @@ public Line() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return this; } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return this; } @@ -741,12 +727,12 @@ public LineOrEmpty() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return this; } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return this; } @@ -771,12 +757,12 @@ static LineOrSpace getInstance() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return this; } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return this; } @@ -788,7 +774,7 @@ public String toString() { /** * Represents a line break which can be flattened into an alternative document - * {@link com.opencastsoftware.prettier4j.Doc.LineOr#altDoc altDoc}. + * {@code altDoc}. */ public static class LineOr extends Doc { private final Doc altDoc; @@ -812,12 +798,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return new LineOr(altDoc.bind(name, value)); } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return new LineOr(altDoc.bind(bindings)); } @@ -867,7 +853,7 @@ public boolean equals(Object obj) { } /** - * Represents an empty {@link com.opencastsoftware.prettier4j.Doc Doc}. + * Represents an empty {@link Doc}. */ public static class Empty extends Doc { private static final Empty INSTANCE = new Empty(); @@ -890,12 +876,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return this; } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return this; } @@ -906,7 +892,7 @@ public String toString() { } /** - * Represents a {@link com.opencastsoftware.prettier4j.Doc Doc} styled with ANSI escape codes. + * Represents a {@link Doc} styled with ANSI escape codes. */ public static class Styled extends Doc { private final Doc doc; @@ -936,12 +922,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return new Styled(doc.bind(name, value), styles); } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return new Styled(doc.bind(bindings), styles); } @@ -992,12 +978,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return this; } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return this; } @@ -1046,12 +1032,12 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { return this; } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { return this; } @@ -1092,7 +1078,7 @@ boolean hasParams() { } @Override - Doc bind(String name, Doc value) { + public Doc bind(String name, Doc value) { if (this.name.equals(name)) { return flattened ? value.flatten() : value; } else { @@ -1101,7 +1087,7 @@ Doc bind(String name, Doc value) { } @Override - Doc bind(Map bindings) { + public Doc bind(Map bindings) { Doc value = bindings.getOrDefault(this.name, this); if (value != this) { return flattened ? value.flatten() : value; @@ -1133,20 +1119,17 @@ public String toString() { } /** - * Construct a {@link com.opencastsoftware.prettier4j.Doc Doc} from the - * {@code text}. + * Construct a {@link Doc} from the {@code text}. * * @param text the input String. - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} representing that - * String. + * @return a {@link Doc Doc} representing that {@link String}. */ public static Doc text(String text) { return new Text(text); } /** - * Construct a {@link com.opencastsoftware.prettier4j.Doc Doc} representing two - * alternative layouts for a document. + * Construct a {@link Doc Doc} representing two alternative layouts for a document. * * @param left the flattened layout for the document. * @param right the expanded layout for the document. @@ -1157,8 +1140,7 @@ static Doc alternatives(Doc left, Doc right) { } /** - * Indent the input {@link com.opencastsoftware.prettier4j.Doc Doc} by - * {@code indent} spaces. + * Indent the input {@link Doc} by {@code indent} spaces. * * @param indent the number of spaces of indent to apply. * @param doc the input document @@ -1169,80 +1151,71 @@ public static Doc indent(int indent, Doc doc) { } /** - * Creates a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a - * line break which cannot be flattened. + * Creates a {@link Doc} representing a line break which cannot be flattened. * - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a line - * break which cannot be flattened. + * @return a {@link Doc} representing a line break which cannot be flattened. */ public static Doc line() { return Line.getInstance(); } /** - * Creates a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a - * line break which may be flattened into an empty document. + * Creates a {@link Doc} representing a line break which may be flattened into an empty document. * - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a line - * break which may be flattened into an empty document. + * @return a {@link Doc} representing a line break which may be flattened into an empty document. */ public static Doc lineOrEmpty() { return LineOrEmpty.getInstance(); } /** - * Creates a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a - * line break which may be flattened into a single space character. + * Creates a {@link Doc} representing a line break which may be flattened into a single space character. * - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a line - * break which may be flattened into a single space character. + * @return a {@link Doc} representing a line break which may be flattened into a single space character. */ public static Doc lineOrSpace() { return LineOrSpace.getInstance(); } /** - * Creates an empty {@link com.opencastsoftware.prettier4j.Doc Doc}. + * Creates an empty {@link Doc}. * - * @return an empty {@link com.opencastsoftware.prettier4j.Doc Doc}. + * @return an empty {@link Doc}. */ public static Doc empty() { return Empty.getInstance(); } /** - * Creates a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a line - * break which may be flattened into an alternative document {@code altDoc}. + * Creates a {@link Doc} representing a line break which may be flattened into + * an alternative document {@code altDoc}. * * @param altDoc the alternative document to use if the line break is flattened. - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a line - * break which may be flattened into an alternative document - * {@code altDoc}. + * @return a {@link Doc} representing a line break which may be flattened into + an alternative document {@code altDoc}. */ public static Doc lineOr(Doc altDoc) { return new LineOr(altDoc); } /** - * Creates a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a line - * break which may be flattened into the alternative text {@code altText}. + * Creates a {@link Doc} representing a line break which may be flattened into + * the alternative text {@code altText}. * * @param altText the alternative text to use if the line break is flattened. - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} representing a line - * break which may be flattened into the alternative text - * {@code altText}. + * @return a {@link Doc} representing a line break which may be flattened into + * the alternative text {@code altText}. */ public static Doc lineOr(String altText) { return new LineOr(text(altText)); } /** - * Styles the input {@link com.opencastsoftware.prettier4j.Doc Doc} using the styles - * provided via {@code styles}. + * Styles the input {@link Doc} using the styles provided via {@code styles}. * * @param doc the input document. * @param styles the styles to use to decorate the input {@code doc}. - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} decorated with the ANSI styles provided. + * @return a {@link Doc} decorated with the ANSI styles provided. * @see Styles * @see com.opencastsoftware.prettier4j.ansi.Color Color */ @@ -1251,7 +1224,7 @@ public static Doc styled(Doc doc, Styles.StylesOperator ...styles) { } /** - * Creates a {@link Doc} which acts as a placeholder for a parameter {@link Doc} that will be provided + * Creates a {@link Doc} which acts as a placeholder for an argument {@link Doc} that will be provided * by {@link Doc#bind(String, Doc) binding} parameters prior to {@link Doc#render(int) render}ing. * @param name the name of the parameter. * @return a parameter {@link Doc}. @@ -1315,12 +1288,10 @@ public static Doc intersperse(Doc separator, Stream documents) { } /** - * Creates a {@link com.opencastsoftware.prettier4j.Doc Doc} which represents a - * group that can be flattened into a more compact layout. + * Creates a {@link Doc} which represents a group that can be flattened into a more compact layout. * * @param doc the document which is declared as a group which may be flattened. - * @return a {@link com.opencastsoftware.prettier4j.Doc Doc} which represents a - * group that can be flattened into a more compact layout. + * @return a {@link Doc} which represents a group that can be flattened into a more compact layout. */ public static Doc group(Doc doc) { return alternatives(doc.flatten(), doc); @@ -1334,8 +1305,7 @@ public static Doc group(Doc doc) { * * @param remaining the remaining space on the current line. * @param entries the entries we'd like to fit onto this line - * @return true if we can fit all - * {@link com.opencastsoftware.prettier4j.Doc.Text entries} up to the + * @return true if we can fit all {@link Doc.Text entries} up to the * next line break into the remaining characters of the current line. */ static boolean fits(int remaining, Deque> entries) { @@ -1385,8 +1355,7 @@ static Deque> chooseLayout(Doc left, Doc right, RenderOp /** * Traverse the input {@code doc} recursively, eliminating all nodes except for - * {@link com.opencastsoftware.prettier4j.Doc.Text Text} and subtypes of - * {@link com.opencastsoftware.prettier4j.Doc.LineOr LineOr}, and producing a + * {@link Doc.Text Text} and subtypes of {@link Doc.LineOr LineOr}, and producing a * queue of entries to be rendered. * * @param doc the document to be rendered. @@ -1463,8 +1432,7 @@ static Deque> normalize(Doc doc, RenderOptions options, } /** - * Renders the input {@link com.opencastsoftware.prettier4j.Doc Doc} into an - * {@link java.lang.Appendable Appendable}, attempting to lay out the document + * Renders the input {@link Doc} into an {@link Appendable}, attempting to lay out the document * according to the rendering {@code options}. * * @param doc the document to be rendered. @@ -1507,8 +1475,7 @@ public static void render(Doc doc, RenderOptions options, Appendable output) thr } /** - * Renders the input {@link com.opencastsoftware.prettier4j.Doc Doc} into an - * {@link java.lang.Appendable Appendable}, attempting to lay out the document + * Renders the input {@link Doc} into an {@link Appendable}, attempting to lay out the document * according to the {@link RenderOptions#defaults() default} rendering options. * * @param doc the document to be rendered. @@ -1520,13 +1487,12 @@ public static void render(Doc doc, Appendable output) throws IOException { } /** - * Renders the input {@link com.opencastsoftware.prettier4j.Doc Doc} into a - * {@link java.lang.String String}, attempting to lay out the document + * Renders the input {@link Doc} into a {@link String}, attempting to lay out the document * according to the rendering {@code options}. * * @param doc the document to be rendered. * @param options the options to use for rendering. - * @return the document laid out as a {@link java.lang.String String}. + * @return the document laid out as a {@link String}. */ public static String render(Doc doc, RenderOptions options) { StringBuilder output = new StringBuilder(); @@ -1541,12 +1507,11 @@ public static String render(Doc doc, RenderOptions options) { } /** - * Renders the input {@link com.opencastsoftware.prettier4j.Doc Doc} into a - * {@link java.lang.String String}, attempting to lay out the document + * Renders the input {@link Doc} into a {@link String}, attempting to lay out the document * according to the {@link RenderOptions#defaults() default} rendering options. * * @param doc the document to be rendered. - * @return the document laid out as a {@link java.lang.String String}. + * @return the document laid out as a {@link String}. */ public static String render(Doc doc) { return render(doc, RenderOptions.defaults()); diff --git a/src/main/java/com/opencastsoftware/prettier4j/RenderOptions.java b/src/main/java/com/opencastsoftware/prettier4j/RenderOptions.java index f777c82..71eb273 100644 --- a/src/main/java/com/opencastsoftware/prettier4j/RenderOptions.java +++ b/src/main/java/com/opencastsoftware/prettier4j/RenderOptions.java @@ -6,7 +6,12 @@ import java.util.Objects; +/** + * Options which determine how {@link Doc}s are rendered. + */ public class RenderOptions { + private static final RenderOptions DEFAULT = new RenderOptions(80, true); + private final int lineWidth; private final boolean emitAnsiEscapes; @@ -15,18 +20,40 @@ public class RenderOptions { this.emitAnsiEscapes = emitAnsiEscapes; } + /** + * Determines the preferred maximum line width. + * + * @return the preferred maximum line width. + */ public int lineWidth() { return this.lineWidth; } + /** + * Determines whether to emit ANSI escape code sequences. + * + * @return whether to emit ANSI escape code sequences. + */ public boolean emitAnsiEscapes() { return this.emitAnsiEscapes; } + /** + * Create a {@link RenderOptions} populated with default values. + *

    + * This configures a preferred maximum line width of 80 characters, + * and enables ANSI escape code sequences. + * + * @return the default rendering options. + */ public static RenderOptions defaults() { - return new RenderOptions(80, true); + return DEFAULT; } + /** + * Creates a {@link Builder} for {@link RenderOptions}. + * @return a {@link RenderOptions} builder. + */ public static Builder builder() { return new Builder(); } @@ -52,20 +79,40 @@ public String toString() { ']'; } + /** + * A builder for configuring {@link RenderOptions}. + */ public static class Builder { private int lineWidth; private boolean emitAnsiEscapes; private Builder() {} + /** + * Build the resulting {@link RenderOptions}. + * + * @return the {@link RenderOptions}. + */ public RenderOptions build() { return new RenderOptions(this.lineWidth, this.emitAnsiEscapes); } + /** + * Set the preferred maximum rendering width. + * + * @param width the preferred maximum rendering width. + * @return this {@link Builder} for fluent usage. + */ public Builder lineWidth(int width) { this.lineWidth = width; return this; } + /** + * Set whether to emit ANSI escape code sequences. + * + * @param emitAnsi whether to emit ANSI escape code sequences. + * @return this {@link Builder} for fluent usage. + */ public Builder emitAnsiEscapes(boolean emitAnsi) { this.emitAnsiEscapes = emitAnsi; return this;