Javadocs api and core (#313)

* Javadocs!!!

Signed-off-by: Francesco Guardiani <[email protected]>

* Missing module name?

Signed-off-by: Francesco Guardiani <[email protected]>

* Excluding javadocs

Signed-off-by: Francesco Guardiani <[email protected]>

* clean install only release artifacts, but verify them all!

Signed-off-by: Francesco Guardiani <[email protected]>

* Reverted the crazy idea to use the release profile

Signed-off-by: Francesco Guardiani <[email protected]>

* Suggestions

Signed-off-by: Francesco Guardiani <[email protected]>

* Suggestion

Signed-off-by: Francesco Guardiani <[email protected]>

* Nit

Signed-off-by: Francesco Guardiani <[email protected]>

* Nit

Signed-off-by: Francesco Guardiani <[email protected]>

* Nit

Signed-off-by: Francesco Guardiani <[email protected]>

Author: slinkydeveloper

amqp/pom.xml

@@ -16,8 +16,10 @@
     <properties>
        <protonj.version>0.33.7</protonj.version>
        <jsr305.version>3.0.2</jsr305.version>
+        <module-name>io.cloudevents.amqp.proton</module-name>
     </properties>
-	<dependencies>
+
+    <dependencies>
 		<dependency>
 			<groupId>org.apache.qpid</groupId>
 			<artifactId>proton-j</artifactId>

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="https://github.com/cloudevents/spec/blob/v1.0/spec.md">CloudEvents specification</a>
+ * as specified by the <a href="https://github.com/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="https://github.com/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="https://github.com/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 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 CloudEventContextWriter {
 
     /**
-     * End the visit with a data field
+     * End the write 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 write.
      *
      * @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;
 }

benchmarks/pom.xml

@@ -34,6 +34,7 @@
         <javac.target>1.8</javac.target>
         <!-- Name of the benchmark Uber-JAR to generate. -->
         <uberjar.name>benchmarks</uberjar.name>
+        <maven.javadoc.skip>true</maven.javadoc.skip>
     </properties>
 
     <dependencies>