[FAB-16655] Warnings as errors for Java chaincode docs

Enable warnings as errors using -Xwerror, enable all
linting checks with -Xdoclint:all, and fix all the
resulting errors.

Signed-off-by: Simon Stone <[email protected]>
Change-Id: Iac41065811edef7ba734c8ab40c39fd04ee0c0ee

Author: Simon Stone

fabric-chaincode-example-sacc-jars/src/main/java/org/hyperledger/fabric/example/SimpleAsset.java

@@ -19,7 +19,8 @@ public class SimpleAsset implements ContractInterface {
      * or to migrate data.
      *
      * @param ctx {@link Context} to operate proposal and ledger
-     * @return response
+     * @param key key
+     * @param value value
      */
     @Transaction
     public void init(Context ctx, String key, String value) {
@@ -30,7 +31,7 @@ public void init(Context ctx, String key, String value) {
      * get returns the value of the specified asset key
      *
      * @param ctx {@link Context} to operate proposal and ledger
-     * @param args key
+     * @param key key
      * @return value
      */
     @Transaction
@@ -47,7 +48,8 @@ public String get(Context ctx, String key) {
      * it will override the value with the new one
      *
      * @param ctx {@link Context} to operate proposal and ledger
-     * @param args key and value
+     * @param key key
+     * @param value value
      * @return value
      */
     @Transaction

fabric-chaincode-shim/build.gradle

@@ -170,7 +170,7 @@ task licenseCheck {
 
 
 javadoc {
-    failOnError = false
+    failOnError = true
     excludes = ['org/hyperledger/fabric/contract/ContextFactory.java',
                 'org/hyperledger/fabric/contract/ContractRouter.java',
                 'org/hyperledger/fabric/contract/ContractRuntimeException.java',
@@ -188,7 +188,8 @@ javadoc {
 
 if (JavaVersion.current().isJava8Compatible()) {
     project.tasks.withType(Javadoc) {
-        options.addStringOption('Xdoclint:none', '-quiet')
+        options.addStringOption('Xdoclint:all', '-quiet')
+        options.addStringOption('Xwerror', '-quiet')
     }
 }
 

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/ContractInterface.java

@@ -27,7 +27,7 @@
  * The sequence of calls is
  *
  * <pre>
- * createContext()  -> beforeTransaction() -> the transaction function -> afterTransaction()
+ * createContext()  -&gt; beforeTransaction() -&gt; the transaction function -&gt; afterTransaction()
  * </pre>
  * <p>
  * If any of these functions throws an exception it is considered an error case,
@@ -46,8 +46,6 @@
  * {@link #afterTransaction(Context, Object)} or between separate transaction functions when
  * called directory, then a subclass of the
  * {@link Context} should be provided.
- * <p>
- *
  */
 public interface ContractInterface {
 

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/shim/Chaincode.java

@@ -18,12 +18,16 @@ public interface Chaincode {
     /**
      * Called during an instantiate transaction after the container has been
      * established, allowing the chaincode to initialize its internal data.
+     * @param stub the chaincode stub
+     * @return the chaincode response
      */
     public Response init(ChaincodeStub stub);
 
     /**
      * Called for every Invoke transaction. The chaincode may change its state
      * variables.
+     * @param stub the chaincode stub
+     * @return the chaincode response
      */
     public Response invoke(ChaincodeStub stub);
 

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/shim/ChaincodeStub.java

@@ -199,10 +199,10 @@ public interface ChaincodeStub {
      * unbounded range query on start or end.
      * This call is only supported in a read only transaction.
      *
-     * @param startKey
-     * @param endKey
-     * @param pageSize
-     * @param bookmark
+     * @param startKey the start key
+     * @param endKey the end key
+     * @param pageSize the page size
+     * @param bookmark the bookmark
      * @return QueryIterator
      */
     QueryResultsIteratorWithMetadata<KeyValue> getStateByRangeWithPagination(String startKey, String endKey, int pageSize, String bookmark);
@@ -215,8 +215,6 @@ public interface ChaincodeStub {
      * If a full composite key is specified, it will not match itself, resulting
      * in no keys being returned.
      * <p>
-     *
-     * <p>
      * This method takes responsibility to correctly parse the {@link CompositeKey} from a String
      * and behaves exactly as {@link ChaincodeStub#getStateByPartialCompositeKey(CompositeKey)}.
      * </p>
@@ -273,9 +271,9 @@ public interface ChaincodeStub {
      * can be used as a value to the bookmark argument. Otherwise, an empty string must be passed as bookmark. <p>
      * This call is only supported in a read only transaction.
      *
-     * @param compositeKey
-     * @param pageSize
-     * @param bookmark
+     * @param compositeKey the composite key
+     * @param pageSize the page size
+     * @param bookmark the bookmark
      * @return QueryIterator
      */
     QueryResultsIteratorWithMetadata<KeyValue> getStateByPartialCompositeKeyWithPagination(CompositeKey compositeKey, int pageSize, String bookmark);
@@ -326,9 +324,9 @@ public interface ChaincodeStub {
      * can be used as a value to the bookmark argument. Otherwise, an empty string must be passed as bookmark. <p>
      * This call is only supported in a read only transaction.
      *
-     * @param query
-     * @param pageSize
-     * @param bookmark
+     * @param query the query
+     * @param pageSize the page size
+     * @param bookmark the bookmark
      * @return QueryIterator
      */
     QueryResultsIteratorWithMetadata<KeyValue> getQueryResultWithPagination(String query, int pageSize, String bookmark);
@@ -365,7 +363,7 @@ public interface ChaincodeStub {
     /**
      * @param collection name of the collection
      * @param key        name of the value
-     * @return
+     * @return the private data hash
      */
     byte[] getPrivateDataHash(String collection, String key);
 

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/shim/ext/sbe/StateBasedEndorsement.java

@@ -17,7 +17,8 @@
  */
 public interface StateBasedEndorsement {
     /**
-     * The endorsement policy as bytes
+     * Get the endorsement policy as bytes
+     * @return the endorsement policy as bytes
      */
     byte[] policy();
 
@@ -29,15 +30,15 @@ public interface StateBasedEndorsement {
      * likely going to be the PEER role, while the MEMBER role is the suited
      * one if it does not.
      *
-     * @param roleType
-     * @param organizations
+     * @param roleType the MSP role type
+     * @param organizations the list of organizations
      */
     void addOrgs(RoleType roleType, String... organizations);
 
     /**
      * deletes the specified channel orgs from the existing key-level endorsement
      * policy for this KVS key.
-     * @param organizations
+     * @param organizations the list of organizations
      */
     void delOrgs(String... organizations);
 

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/shim/ext/sbe/impl/StateBasedEndorsementFactory.java

@@ -23,7 +23,7 @@ public static synchronized StateBasedEndorsementFactory getInstance() {
      * Constructs a state-based endorsement policy from a given
      * serialized EP byte array. If the byte array is empty, a new EP is created.
      *
-     * @param ep
+     * @param ep serialized endorsement policy
      * @return New StateBasedEndorsement instance
      */
     public StateBasedEndorsement newStateBasedEndorsement(byte[] ep) {

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/shim/ledger/CompositeKey.java

@@ -64,6 +64,7 @@ public static CompositeKey parseCompositeKey(String compositeKey) {
      * is the namespace for compositeKey). This helps in avoding simple/composite
      * key collisions.
      *
+     * @param keys the list of simple keys
      * @throws CompositeKeyFormatException if First character of the key
      */
     public static void validateSimpleKeys(String... keys) {

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/shim/ledger/QueryResultsIterator.java

@@ -9,7 +9,7 @@
 /**
  * QueryResultsIterator allows a chaincode to iterate over a set of key/value pairs returned by range, execute and history queries.
  *
- * @param <T>
+ * @param <T> the type of elements returned by the iterator
  */
 public interface QueryResultsIterator<T> extends Iterable<T>, AutoCloseable {
 }

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/shim/ledger/QueryResultsIteratorWithMetadata.java

@@ -12,7 +12,7 @@
  * QueryResultsIteratorWithMetadata allows a chaincode to iterate over a set of key/value pairs returned by range, execute and history queries.
  * In addition, it store {@link org.hyperledger.fabric.protos.peer.ChaincodeShim.QueryResponseMetadata}, returned by pagination range queries
  *
- * @param <T>
+ * @param <T> the type of elements returned by the iterator
  */
 public interface QueryResultsIteratorWithMetadata<T> extends Iterable<T>, AutoCloseable {
     ChaincodeShim.QueryResponseMetadata getMetadata();