Fix Javadocs and implement their aggregation [ECR-3329]: (#1006)

- Fix broken Javadocs.

- Also add a script to generate aggregated Javadocs
for published modules. As each has its unique root package,
it is easier to see which class (or package) is in which module.

The Javadoc links are to be changed in all projects as part of the release procedure.

Author: dmitry-timofeev

exonum-java-binding/common/src/main/java/com/exonum/binding/common/blockchain/TransactionLocation.java

@@ -47,7 +47,7 @@ public static TransactionLocation valueOf(long height, long indexInBlock) {
   /**
    * Provides a Gson type adapter for this class.
    *
-   * @see com.exonum.binding.common.serialization.json.TransactionLocationAdapterFactory
+   * @see com.exonum.binding.common.serialization.json.CommonTypeAdapterFactory
    */
   public static TypeAdapter<TransactionLocation> typeAdapter(Gson gson) {
     return new AutoValue_TransactionLocation.GsonTypeAdapter(gson);

exonum-java-binding/common/src/main/java/com/exonum/binding/common/proofs/list/CheckedListProof.java

@@ -22,7 +22,7 @@
 /**
  * A proof that some elements exist in a proof list.
  * Example usage:
- * <pre><code>
+ * <pre>{@code
  * HashCode expectedRootHash = // get a known root hash from block proof //
  * UncheckedListProof proof = new UncheckedListProofAdapter(rootProofNode, serializer);
  * // Check the proof
@@ -32,7 +32,7 @@
  *   // Get and use elements
  *   NavigableMap value = checkedProof.getElements();
  * }
- * </code></pre>
+ * }</pre>
  */
 public interface CheckedListProof<E> extends CheckedProof {
   /**

exonum-java-binding/common/src/main/java/com/exonum/binding/common/proofs/map/CheckedMapProof.java

@@ -26,7 +26,7 @@
  * In case of incorrect proof all methods (except for getStatus and compareWithRootHash)
  * throw IllegalStateException.
  * Example usage:
- * <pre><code>
+ * <pre>{@code
  * ByteString key = "The key for which I want a proved value".getBytes();
  * HashCode expectedRootHash = // get a known root hash from block proof //
  * UncheckedMapProof proof = requestProofForKey(key);
@@ -37,7 +37,7 @@
  *   // Get and use the value(s)
  *   ByteString value = checked.get(key);
  * }
- * </code></pre>
+ * }</pre>
  */
 public interface CheckedMapProof extends CheckedProof {
   /**

exonum-java-binding/core/src/main/java/com/exonum/binding/core/service/Service.java

@@ -106,11 +106,11 @@ default List<HashCode> getStateHashes(Snapshot snapshot) {
    * and you have an endpoint «/timestamp», use «/timestamp» as the endpoint name when defining
    * the handler and it will be available by path «/api/services/timestamping/timestamp»:
    *
-   * <pre><code>
+   * <pre>{@code
    * router.get("/timestamp").handler((rc) -> {
    *   rc.response().end("2019-04-01T10:15:30+02:00[Europe/Kiev]");
    * });
-   * </code></pre>
+   * }</pre>
    *
    * @param node a set-up Exonum node, providing an interface to access
    *             the current blockchain state and submit transactions

exonum-java-binding/generate-javadocs.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Builds an archive with Javadocs from published artifacts.
+# The archive is put in './target/site'
+
+# Fail immediately in case of errors and/or unset variables
+set -eu -o pipefail
+
+# Build the Javadocs
+mvn clean javadoc:aggregate -Dmaven.javadoc.skip=false \
+  `# Include only the published artifacts. As package filtering wildcards are rather limited,\
+   it is more convenient to specify the list of projects:` \
+  --projects com.exonum.binding:exonum-java-binding-parent,common,core,testkit,time-oracle
+
+# Create an archive to be published
+TARGET="${PWD}/target/site/"
+cd "${TARGET}"
+
+ARCHIVE_NAME="java-binding-apidocs.tgz"
+tar cvaf ${ARCHIVE_NAME} "apidocs/"
+
+echo "[INFO] Javadoc archive created in ${TARGET}/${ARCHIVE_NAME}"

exonum-java-binding/testkit/src/main/java/com/exonum/binding/testkit/EmulatedNode.java

@@ -44,16 +44,16 @@ public EmulatedNode(int validatorId, KeyPair serviceKeyPair) {
   }
 
   /**
-   * Returns a node type - either {@link EmulatedNodeType.VALIDATOR} or
-   * {@link EmulatedNodeType.AUDITOR}.
+   * Returns a node type - either {@link EmulatedNodeType#VALIDATOR} or
+   * {@link EmulatedNodeType#AUDITOR}.
    */
   public EmulatedNodeType getNodeType() {
     return validatorId.isPresent() ? EmulatedNodeType.VALIDATOR : EmulatedNodeType.AUDITOR;
   }
 
   /**
-   * Returns a validator id if this node is a validator or {@link OptionalInt.EMPTY} is this is an
-   * auditor node.
+   * Returns a validator id if this node is a validator or {@link OptionalInt#empty()} if this is
+   * an auditor node.
    */
   public OptionalInt getValidatorId() {
     return validatorId;

exonum-java-binding/testkit/src/main/java/com/exonum/binding/testkit/TestKit.java

@@ -36,6 +36,7 @@
 import com.exonum.binding.core.service.Service;
 import com.exonum.binding.core.service.ServiceModule;
 import com.exonum.binding.core.service.adapters.UserServiceAdapter;
+import com.exonum.binding.core.storage.database.Fork;
 import com.exonum.binding.core.storage.database.Snapshot;
 import com.exonum.binding.core.storage.indices.KeySetIndexProxy;
 import com.exonum.binding.core.storage.indices.MapIndex;
@@ -49,6 +50,7 @@
 import com.google.common.collect.Streams;
 import com.google.inject.Guice;
 import com.google.inject.Injector;
+import io.vertx.ext.web.Router;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -68,13 +70,13 @@
  * state.
  *
  * <p>Only the emulated node has a pool of unconfirmed transactions where a service can submit new
- * transaction messages through {@linkplain Node#submitTransaction(RawTransaction)}; or the test
+ * transaction messages through {@link Node#submitTransaction(RawTransaction)}; or the test
  * code through {@link #createBlockWithTransactions(TransactionMessage...)}. All transactions
  * from the pool are committed when a new block is created with {@link #createBlock()}.
  *
- * <p>When TestKit is created, Exonum blockchain instance is initialized - service instances are
- * {@linkplain UserServiceAdapter#initialize(long) initialized} and genesis block is committed.
- * Then the {@linkplain UserServiceAdapter#mountPublicApiHandler(long) public API handlers} are
+ * <p>When TestKit is created, Exonum blockchain instance is initialized — service instances are
+ * {@linkplain Service#initialize(Fork) initialized} and genesis block is committed.
+ * Then the {@linkplain Service#createPublicApiHandlers(Node, Router) public API handlers} are
  * created.
  *
  * @see <a href="https://exonum.com/doc/version/0.11/get-started/test-service/">TestKit documentation</a>