Javadocs!!!

Signed-off-by: Francesco Guardiani <francescoguard@gmail.com>

Author: slinkydeveloper

api/src/main/java/io/cloudevents/CloudEvent.java

@@ -20,12 +20,12 @@
 
 /**
  * Interface representing an in memory read only representation of a CloudEvent,
- * as specified by the <a href="/cloudevents/spec/blob/v1.0/spec.md">CloudEvents specification</a>
+ * as specified by the <a href="/cloudevents/spec/blob/v1.0/spec.md">CloudEvents specification</a>.
  */
 public interface CloudEvent extends CloudEventContext {
 
     /**
-     * The event data
+     * @return The event data, if any, otherwise {@code null}
      */
     @Nullable
     CloudEventData getData();

api/src/main/java/io/cloudevents/SpecVersion.java

@@ -29,11 +29,17 @@
  */
 @ParametersAreNonnullByDefault
 public enum SpecVersion {
+    /**
+     * @see <a href="https://github.com/cloudevents/spec/releases/tag/v0.3">CloudEvents release v0.3</a>
+     */
     V03(
         "0.3",
         Arrays.asList("specversion", "id", "type", "source"),
         Arrays.asList("datacontenttype", "datacontentencoding", "schemaurl", "subject", "time")
     ),
+    /**
+     * @see <a href="https://github.com/cloudevents/spec/releases/tag/v1.0">CloudEvents release v1.0</a>
+     */
     V1(
         "1.0",
         Arrays.asList("specversion", "id", "type", "source"),

api/src/main/java/io/cloudevents/lang/Nullable.java

@@ -27,6 +27,9 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 import static javax.annotation.meta.When.MAYBE;
 
+/**
+ * This annotation is used to define a method parameter or return type as nullable.
+ */
 @Target(value = {METHOD, PARAMETER, FIELD})
 @Retention(value = RUNTIME)
 @Documented

api/src/main/java/io/cloudevents/rw/CloudEventDataMapper.java

@@ -23,6 +23,8 @@
 
 /**
  * Interface to convert a {@link CloudEventData} instance to another one.
+ *
+ * @param <R> the returned {@link CloudEventData} from this mapper.
  */
 @FunctionalInterface
 @ParametersAreNonnullByDefault
@@ -38,7 +40,7 @@ public interface CloudEventDataMapper<R extends CloudEventData> {
     R map(CloudEventData data) throws CloudEventRWException;
 
     /**
-     * No-op identity mapper which can be used as default when no mapper is provided.
+     * @return No-op identity mapper which can be used as default when no mapper is provided.
      */
     static CloudEventDataMapper<CloudEventData> identity() {
         return d -> d;

api/src/main/java/io/cloudevents/rw/CloudEventRWException.java

@@ -17,6 +17,8 @@
 
 package io.cloudevents.rw;
 
+import io.cloudevents.lang.Nullable;
+
 /**
  * This class is the exception Protocol Binding and Event Format implementers can use to signal errors while serializing/deserializing CloudEvent.
  */
@@ -35,9 +37,9 @@ public enum CloudEventRWExceptionKind {
          */
         INVALID_ATTRIBUTE_NAME,
         /**
-         * The extension name is not valid,
-         * because it doesn't follow the <a href="/cloudevents/spec/blob/v1.0/spec.md#attribute-naming-convention">naming convention</a>
-         * enforced by the CloudEvents spec.
+         * The extension name is not valid because it doesn't follow the naming convention enforced by the CloudEvents spec.
+         *
+         * @see <a href="/cloudevents/spec/blob/v1.0/spec.md#attribute-naming-convention">naming convention</a>
          */
         INVALID_EXTENSION_NAME,
         /**
@@ -83,46 +85,77 @@ private CloudEventRWException(CloudEventRWExceptionKind kind, String message, Th
         this.kind = kind;
     }
 
+    /**
+     * @return the {@link CloudEventRWExceptionKind} associated to this exception instance.
+     */
     public CloudEventRWExceptionKind getKind() {
         return kind;
     }
 
+    /**
+     * @param specVersion the invalid input spec version
+     * @return a new {@link CloudEventRWException} instance
+     */
     public static CloudEventRWException newInvalidSpecVersion(String specVersion) {
         return new CloudEventRWException(
             CloudEventRWExceptionKind.INVALID_SPEC_VERSION,
             "Invalid specversion: " + specVersion
         );
     }
 
+    /**
+     * @param attributeName the invalid attribute name
+     * @return a new {@link CloudEventRWException} instance
+     */
     public static CloudEventRWException newInvalidAttributeName(String attributeName) {
         return new CloudEventRWException(
             CloudEventRWExceptionKind.INVALID_ATTRIBUTE_NAME,
             "Invalid attribute: " + attributeName
         );
     }
 
+    /**
+     * @param extensionName the invalid extension name
+     * @return a new {@link CloudEventRWException} instance
+     */
     public static CloudEventRWException newInvalidExtensionName(String extensionName) {
         return new CloudEventRWException(
             CloudEventRWExceptionKind.INVALID_EXTENSION_NAME,
             "Invalid extensions name: " + extensionName
         );
     }
 
+    /**
+     * @param attributeName the invalid attribute name
+     * @param clazz         the type of the attribute
+     * @return a new {@link CloudEventRWException} instance
+     */
     public static CloudEventRWException newInvalidAttributeType(String attributeName, Class<?> clazz) {
         return new CloudEventRWException(
             CloudEventRWExceptionKind.INVALID_ATTRIBUTE_TYPE,
             "Invalid attribute/extension type for \"" + attributeName + "\": " + clazz.getCanonicalName()
         );
     }
 
-    public static CloudEventRWException newInvalidAttributeValue(String attributeName, Object value, Throwable cause) {
+    /**
+     * @param attributeName the invalid attribute name
+     * @param value         the value of the attribute
+     * @param cause         an optional cause identifying the eventual validation error
+     * @return a new {@link CloudEventRWException} instance
+     */
+    public static CloudEventRWException newInvalidAttributeValue(String attributeName, Object value, @Nullable Throwable cause) {
         return new CloudEventRWException(
             CloudEventRWExceptionKind.INVALID_ATTRIBUTE_VALUE,
             "Invalid attribute/extension value for \"" + attributeName + "\": " + value,
             cause
         );
     }
 
+    /**
+     * @param actual  the actual data type
+     * @param allowed the list of allowed data types
+     * @return a new {@link CloudEventRWException} instance
+     */
     public static CloudEventRWException newInvalidDataType(String actual, String... allowed) {
         String message;
         if (allowed.length == 0) {
@@ -136,6 +169,12 @@ public static CloudEventRWException newInvalidDataType(String actual, String...
         );
     }
 
+    /**
+     * @param cause the cause of the conversion failure
+     * @param from  the input data type
+     * @param to    the target data type
+     * @return a new {@link CloudEventRWException} instance
+     */
     public static CloudEventRWException newDataConversion(Throwable cause, String from, String to) {
         return new CloudEventRWException(
             CloudEventRWExceptionKind.DATA_CONVERSION,
@@ -144,17 +183,26 @@ public static CloudEventRWException newDataConversion(Throwable cause, String fr
         );
     }
 
-    public static CloudEventRWException newOther(Throwable cause) {
+    /**
+     * @return a new {@link CloudEventRWException} instance.
+     */
+    public static CloudEventRWException newUnknownEncodingException() {
         return new CloudEventRWException(
-            CloudEventRWExceptionKind.OTHER,
-            cause
+            CloudEventRWExceptionKind.UNKNOWN_ENCODING,
+            "Could not parse. Unknown encoding. Invalid content type or spec version"
         );
     }
 
-    public static CloudEventRWException newUnknownEncodingException() {
+    /**
+     * This wraps a {@link Throwable} in a new generic instance of this exception.
+     *
+     * @param cause the cause of the exception
+     * @return a new {@link CloudEventRWException} instance
+     */
+    public static CloudEventRWException newOther(Throwable cause) {
         return new CloudEventRWException(
-            CloudEventRWExceptionKind.UNKNOWN_ENCODING,
-            "Could not parse. Unknown encoding. Invalid content type or spec version"
+            CloudEventRWExceptionKind.OTHER,
+            cause
         );
     }
 }

api/src/main/java/io/cloudevents/rw/CloudEventReader.java

@@ -30,18 +30,24 @@
 public interface CloudEventReader {
 
     /**
-     * Visit self using the provided visitor factory
+     * Like {@link #read(CloudEventWriterFactory, CloudEventDataMapper)}, but with the identity {@link CloudEventDataMapper}.
      *
-     * @param writerFactory a factory that generates a visitor starting from the SpecVersion of the event
-     * @throws CloudEventRWException if something went wrong during the read.
+     * @see #read(CloudEventWriterFactory, CloudEventDataMapper)
      */
-    default <V extends CloudEventWriter<R>, R> R read(CloudEventWriterFactory<V, R> writerFactory) throws CloudEventRWException {
+    default <W extends CloudEventWriter<R>, R> R read(CloudEventWriterFactory<W, R> writerFactory) throws CloudEventRWException {
         return read(writerFactory, CloudEventDataMapper.identity());
     }
 
     /**
-     * Like {@link CloudEventReader#read(CloudEventWriterFactory)}, but providing a mapper for {@link io.cloudevents.CloudEventData} to be invoked when the data field is available.
+     * Read self using the provided writer factory.
+     *
+     * @param <W>           the {@link CloudEventWriter} type
+     * @param <R>           the return type of the {@link CloudEventWriter}
+     * @param writerFactory a factory that generates a visitor starting from the SpecVersion of the event
+     * @param mapper        the mapper to invoke when building the {@link CloudEventData}
+     * @return the return value returned by {@link CloudEventWriter#end()} or {@link CloudEventWriter#end(CloudEventData)}
+     * @throws CloudEventRWException if something went wrong during the read.
      */
-    <V extends CloudEventWriter<R>, R> R read(CloudEventWriterFactory<V, R> writerFactory, CloudEventDataMapper<? extends CloudEventData> mapper) throws CloudEventRWException;
+    <W extends CloudEventWriter<R>, R> R read(CloudEventWriterFactory<W, R> writerFactory, CloudEventDataMapper<? extends CloudEventData> mapper) throws CloudEventRWException;
 
 }

api/src/main/java/io/cloudevents/rw/CloudEventWriter.java

@@ -28,15 +28,16 @@
 public interface CloudEventWriter<R> extends CloudEventAttributesWriter, CloudEventExtensionsWriter {
 
     /**
-     * End the visit with a data field
+     * End the read with a data payload.
      *
+     * @param data the data to write
      * @return an eventual return value
      * @throws CloudEventRWException if the message writer cannot be ended.
      */
     R end(CloudEventData data) throws CloudEventRWException;
 
     /**
-     * End the visit
+     * End the read.
      *
      * @return an eventual return value
      * @throws CloudEventRWException if the message writer cannot be ended.

api/src/main/java/io/cloudevents/rw/CloudEventWriterFactory.java

@@ -19,8 +19,14 @@
 
 import io.cloudevents.SpecVersion;
 
+/**
+ * This factory is used to enforce setting the {@link SpecVersion} as first step in the writing process.
+ *
+ * @param <W> The type of the {@link CloudEventWriter} created by this factory
+ * @param <R> The return value of the {@link CloudEventWriter} created by this factory
+ */
 @FunctionalInterface
-public interface CloudEventWriterFactory<V extends CloudEventWriter<R>, R> {
+public interface CloudEventWriterFactory<W extends CloudEventWriter<R>, R> {
 
     /**
      * Create a {@link CloudEventWriter} starting from the provided {@link SpecVersion}
@@ -29,5 +35,5 @@ public interface CloudEventWriterFactory<V extends CloudEventWriter<R>, R> {
      * @return the new writer
      * @throws CloudEventRWException if the spec version is invalid or the writer cannot be instantiated.
      */
-    V create(SpecVersion version) throws CloudEventRWException;
+    W create(SpecVersion version) throws CloudEventRWException;
 }

core/src/main/java/io/cloudevents/core/CloudEventUtils.java

@@ -30,16 +30,15 @@
 import io.cloudevents.rw.CloudEventReader;
 
 /**
- * This class contains a set of utility methods to deal with conversions of io.cloudevents related interfaces
+ * This class contains a set of utility methods to deal with conversions of {@link io.cloudevents} related interfaces
  */
 public final class CloudEventUtils {
 
     private CloudEventUtils() {}
 
     /**
      * Convert a {@link CloudEvent} to a {@link CloudEventReader}. This method provides a default implementation
-     * for CloudEvent that doesn't implement {@link CloudEventReader}
-     * for CloudEvent that doesn't implement CloudEventVisitable.
+     * for CloudEvent that doesn't implement {@link CloudEventReader}.
      * <p>
      * It's safe to use the returned {@link CloudEventReader} multiple times.
      *
@@ -94,6 +93,11 @@ public static CloudEvent toEvent(CloudEventReader reader, CloudEventDataMapper<?
 
     /**
      * Get the data contained in {@code event} and map it using the provided mapper.
+     *
+     * @param event  the event eventually containing the data
+     * @param mapper the mapper to use to map the data
+     * @param <R>    the returned {@link CloudEventData} implementation from the provided mapper
+     * @return the data contained in {@code event} and mapped with {@code mapper}, if any, otherwise null
      */
     @Nullable
     public static <R extends CloudEventData> R mapData(CloudEvent event, CloudEventDataMapper<R> mapper) {

core/src/main/java/io/cloudevents/core/data/BytesCloudEventData.java

@@ -5,11 +5,15 @@
 import java.util.Arrays;
 import java.util.Objects;
 
+/**
+ * An implementation of {@link CloudEventData} that wraps a byte array.
+ */
 public class BytesCloudEventData implements CloudEventData {
 
     private final byte[] value;
 
     /**
+     * @param value the bytes to wrap
      * @deprecated use {@link BytesCloudEventData#wrap(byte[])}
      */
     public BytesCloudEventData(byte[] value) {