java: Add Javadoc to messages

CHANGELOG.md

@@ -10,6 +10,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Changed
 - Add exception to TestStepFinished TestRunFinished ([#122](https://github.com/cucumber/messages/pull/122))
 
+### Added
+- [Java] Add javadoc to messages ([#124](https://github.com/cucumber/messages/pull/124))
+
 ## [20.0.0] - 2022-11-14
 ### Changed
 - Add `workerId` field to TestCaseStarted message ([#34](https://github.com/cucumber/messages/pull/34))

Makefile

@@ -3,6 +3,7 @@ schemas = \
 	./jsonschema/Source.json \
 	./jsonschema/Attachment.json \
 	./jsonschema/Location.json \
+	./jsonschema/Exception.json \
 	./jsonschema/SourceReference.json \
 	./jsonschema/Hook.json \
 	./jsonschema/GherkinDocument.json \

java/src/generated/java/io/cucumber/messages/types/Attachment.java

@@ -7,6 +7,22 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Attachment message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ *
+ * //// Attachments (parse errors, execution errors, screenshots, links...)
+ *
+ * An attachment represents any kind of data associated with a line in a
+ * [Source](#io.cucumber.messages.Source) file. It can be used for:
+ *
+ * * Syntax errors during parse time
+ * * Screenshots captured and attached during execution
+ * * Logs captured and attached during execution
+ *
+ * It is not to be used for runtime errors raised/thrown during execution. This
+ * is captured in `TestResult`.
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Attachment {
@@ -39,18 +55,42 @@ public Attachment(
         this.url = url;
     }
 
+    /**
+     * The body of the attachment. If `contentEncoding` is `IDENTITY`, the attachment
+     * is simply the string. If it's `BASE64`, the string should be Base64 decoded to
+     * obtain the attachment.
+     */
     public String getBody() {
         return body;
     }
 
+    /**
+     * Whether to interpret `body` "as-is" (IDENTITY) or if it needs to be Base64-decoded (BASE64).
+     *
+     * Content encoding is *not* determined by the media type, but rather by the type
+     * of the object being attached:
+     *
+     * - string => IDENTITY
+     * - byte array => BASE64
+     * - stream => BASE64
+     */
     public AttachmentContentEncoding getContentEncoding() {
         return contentEncoding;
     }
 
+    /**
+      * Suggested file name of the attachment. (Provided by the user as an argument to `attach`)
+     */
     public Optional<String> getFileName() {
         return Optional.ofNullable(fileName);
     }
 
+    /**
+     * The media type of the data. This can be any valid
+     * [IANA Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml)
+     * as well as Cucumber-specific media types such as `text/x.cucumber.gherkin+plain`
+     * and `text/x.cucumber.stacktrace+plain`
+     */
     public String getMediaType() {
         return mediaType;
     }
@@ -67,6 +107,19 @@ public Optional<String> getTestStepId() {
         return Optional.ofNullable(testStepId);
     }
 
+    /**
+      * A URL where the attachment can be retrieved. This field should not be set by Cucumber.
+     * It should be set by a program that reads a message stream and does the following for
+     * each Attachment message:
+     *
+     * - Writes the body (after base64 decoding if necessary) to a new file.
+     * - Sets `body` and `contentEncoding` to `null`
+     * - Writes out the new attachment message
+     *
+     * This will result in a smaller message stream, which can improve performance and
+     * reduce bandwidth of message consumers. It also makes it easier to process and download attachments
+     * separately from reports.
+     */
     public Optional<String> getUrl() {
         return Optional.ofNullable(url);
     }

java/src/generated/java/io/cucumber/messages/types/Background.java

@@ -7,6 +7,10 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Background message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Background {
@@ -33,6 +37,9 @@ public Background(
         this.id = requireNonNull(id, "Background.id cannot be null");
     }
 
+    /**
+     * The location of the `Background` keyword
+     */
     public Location getLocation() {
         return location;
     }

java/src/generated/java/io/cucumber/messages/types/Ci.java

@@ -7,6 +7,12 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Ci message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ *
+ * CI environment
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Ci {
@@ -27,14 +33,23 @@ public Ci(
         this.git = git;
     }
 
+    /**
+     * Name of the CI product, e.g. "Jenkins", "CircleCI" etc.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+      * Link to the build
+     */
     public Optional<String> getUrl() {
         return Optional.ofNullable(url);
     }
 
+    /**
+      * The build number. Some CI servers use non-numeric build numbers, which is why this is a string
+     */
     public Optional<String> getBuildNumber() {
         return Optional.ofNullable(buildNumber);
     }

java/src/generated/java/io/cucumber/messages/types/Comment.java

@@ -7,6 +7,12 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Comment message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ *
+ * A comment in a Gherkin document
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Comment {
@@ -21,10 +27,16 @@ public Comment(
         this.text = requireNonNull(text, "Comment.text cannot be null");
     }
 
+    /**
+     * The location of the comment
+     */
     public Location getLocation() {
         return location;
     }
 
+    /**
+     * The text of the comment
+     */
     public String getText() {
         return text;
     }

java/src/generated/java/io/cucumber/messages/types/DataTable.java

@@ -7,6 +7,10 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the DataTable message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class DataTable {

java/src/generated/java/io/cucumber/messages/types/DocString.java

@@ -7,6 +7,10 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the DocString message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class DocString {

java/src/generated/java/io/cucumber/messages/types/Duration.java

@@ -7,6 +7,13 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Duration message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ *
+ * The structure is pretty close of the Timestamp one. For clarity, a second type
+ * of message is used.
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Duration {
@@ -25,6 +32,12 @@ public Long getSeconds() {
         return seconds;
     }
 
+    /**
+     * Non-negative fractions of a second at nanosecond resolution. Negative
+     * second values with fractions must still have non-negative nanos values
+     * that count forward in time. Must be from 0 to 999,999,999
+     * inclusive.
+     */
     public Long getNanos() {
         return nanos;
     }

java/src/generated/java/io/cucumber/messages/types/Envelope.java

@@ -7,6 +7,17 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Envelope message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ *
+ * When removing a field, replace it with reserved, rather than deleting the line.
+ * When adding a field, add it to the end and increment the number by one.
+ * See https://developers.google.com/protocol-buffers/docs/proto#updating for details
+ *
+ * All the messages that are passed between different components/processes are Envelope
+ * messages.
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Envelope {

java/src/generated/java/io/cucumber/messages/types/Examples.java

@@ -7,6 +7,10 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Examples message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Examples {
@@ -39,6 +43,9 @@ public Examples(
         this.id = requireNonNull(id, "Examples.id cannot be null");
     }
 
+    /**
+     * The location of the `Examples` keyword
+     */
     public Location getLocation() {
         return location;
     }

java/src/generated/java/io/cucumber/messages/types/Exception.java

@@ -7,6 +7,12 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Exception message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ *
+ * A simplified representation of an exception
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Exception {
@@ -21,10 +27,16 @@ public Exception(
         this.message = message;
     }
 
+    /**
+     * The type of the exception that caused this result. E.g. "Error" or "org.opentest4j.AssertionFailedError"
+     */
     public String getType() {
         return type;
     }
 
+    /**
+      * The message of exception that caused this result. E.g. expected: <"a"> but was: <"b">
+     */
     public Optional<String> getMessage() {
         return Optional.ofNullable(message);
     }

java/src/generated/java/io/cucumber/messages/types/Feature.java

@@ -7,6 +7,10 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the Feature message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class Feature {
@@ -36,30 +40,51 @@ public Feature(
         this.children = unmodifiableList(new ArrayList<>(requireNonNull(children, "Feature.children cannot be null")));
     }
 
+    /**
+     * The location of the `Feature` keyword
+     */
     public Location getLocation() {
         return location;
     }
 
+    /**
+     * All the tags placed above the `Feature` keyword
+     */
     public java.util.List<Tag> getTags() {
         return tags;
     }
 
+    /**
+     * The [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code of the Gherkin document
+     */
     public String getLanguage() {
         return language;
     }
 
+    /**
+     * The text of the `Feature` keyword (in the language specified by `language`)
+     */
     public String getKeyword() {
         return keyword;
     }
 
+    /**
+     * The name of the feature (the text following the `keyword`)
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * The line(s) underneath the line with the `keyword` that are used as description
+     */
     public String getDescription() {
         return description;
     }
 
+    /**
+     * Zero or more children
+     */
     public java.util.List<FeatureChild> getChildren() {
         return children;
     }

java/src/generated/java/io/cucumber/messages/types/FeatureChild.java

@@ -7,6 +7,12 @@
 import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Represents the FeatureChild message in Cucumber's message protocol
+ * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ *
+ * A child node of a `Feature` node
+ */
 // Generated code
 @SuppressWarnings("unused")
 public final class FeatureChild {