Documentation: Fixed and added javadoc comments for existing classes (#1026)

* added documentation

* added documentation

* Fixed mvn javadoc:javadoc errors, warnings and added missing documentation.

* implemented review comments

* removed unused import

Author: legacycode

src/main/java/com/iota/iri/IRI.java

@@ -60,6 +60,12 @@ public static void main(String[] args) throws Exception {
         IRILauncher.main(args);
     }
 
+    /**
+     * Reads the logging configuration file and logging level from system properties. You can set this values as
+     * arguments to the Java VM by passing <code>-Dlogback.configurationFile=/path/to/config.xml -Dlogging-level=DEBUG</code>
+     * to the Java VM. If no system properties are specified the logback default values and logging-level INFO will
+     * be used.
+     */
     private static void configureLogging() {
         String config = System.getProperty("logback.configurationFile");
         String level = System.getProperty("logging-level", "").toUpperCase();
@@ -178,6 +184,14 @@ private static IotaConfig createConfiguration(String[] args) {
             return iotaConfig;
         }
 
+        /**
+         * Parses the command line arguments for a config file that can be provided by parameter <code>-c</code>
+         * or parameter <code>--config</code>. If no filename was provided we fall back to <code>iota.ini</code> file.
+         * If no <code>iota.ini</code> file can be found return null.
+         *
+         * @param args command line arguments passed to main method.
+         * @return File the chosen file to use as config, or null.
+         */
         private static File chooseConfigFile(String[] args) {
             int index = Math.max(ArrayUtils.indexOf(args, "-c"), ArrayUtils.indexOf(args, "--config"));
             if (index != -1) {

src/main/java/com/iota/iri/conf/ConfigFactory.java

@@ -13,8 +13,17 @@
 import java.io.IOException;
 import java.util.Properties;
 
+/**
+ * Creates the global {@link IotaConfig} object with iri specific settings.
+ */
 public class ConfigFactory {
 
+    /**
+     * Creates the {@link IotaConfig} object for {@link TestnetConfig} or {@link MainnetConfig}.
+     *
+     * @param isTestnet true if {@link TestnetConfig} should be created.
+     * @return return the {@link IotaConfig} configuration.
+     */
     public static IotaConfig createIotaConfig(boolean isTestnet) {
         IotaConfig iotaConfig;
         if (isTestnet) {
@@ -26,8 +35,18 @@ public static IotaConfig createIotaConfig(boolean isTestnet) {
         return iotaConfig;
     }
 
-    public static IotaConfig createFromFile(File configFile, boolean testnet) throws IOException,
-            IllegalArgumentException {
+    /**
+     * Creates the {@link IotaConfig} object for {@link TestnetConfig} or {@link MainnetConfig} from config file. Parse
+     * the config file for <code>TESTNET=true</code>. If <code>TESTNET=true</code> is found we creates the
+     * {@link TestnetConfig} object, else creates the {@link MainnetConfig}.
+     *
+     * @param configFile A property file with configuration options.
+     * @param testnet When true a {@link TestnetConfig} is created.
+     * @return the {@link IotaConfig} configuration.
+     *
+     * @throws IOException When config file could not be found.
+     */
+    public static IotaConfig createFromFile(File configFile, boolean testnet) throws IOException {
         IotaConfig iotaConfig;
 
         try (FileInputStream confStream = new FileInputStream(configFile)) {

src/main/java/com/iota/iri/conf/SnapshotConfig.java

@@ -41,7 +41,7 @@ public interface SnapshotConfig extends Config {
     long getSnapshotTime();
 
     /**
-     * return {@value Descriptions#SNAPSHOT_FILE}
+     * @return {@value Descriptions#SNAPSHOT_FILE}
      */
     String getSnapshotFile();
 

src/main/java/com/iota/iri/service/API.java

@@ -839,7 +839,7 @@ private synchronized AbstractResponse getTipsStatement() throws Exception {
       * These trytes are returned by <tt>attachToTangle</tt>, or by doing proof of work somewhere else.
       *
       * @param trytes Transaction data to be stored.
-      * @throws Exception When storing or updating a transaction fails
+      * @throws Exception When storing or updating a transaction fails.
       **/
     public void storeTransactionsStatement(List<String> trytes) throws Exception {
         final List<TransactionViewModel> elements = new LinkedList<>();

src/main/java/com/iota/iri/service/ValidationException.java

@@ -11,6 +11,7 @@ public ValidationException() {
 
     /**
      * Initializes a new instance of the ValidationException with the specified detail message.
+     * @param msg message shown in exception details.
      */
     public ValidationException(String msg) {
         super(msg);

src/main/java/com/iota/iri/service/dto/GetNeighborsResponse.java

@@ -30,7 +30,7 @@ public class GetNeighborsResponse extends AbstractResponse {
     private Neighbor[] neighbors;
 
     /**
-     * 
+     * @see com.iota.iri.service.dto.GetNeighborsResponse.Neighbor
      * @return {@link #neighbors}
      */
     public Neighbor[] getNeighbors() {

src/main/java/com/iota/iri/storage/PersistenceProvider.java

@@ -44,8 +44,8 @@ public interface PersistenceProvider {
 
     /**
      * Atomically delete all {@code models}.
-     * @param models key value pairs that to be expunged from the db
-     * @throws Exception
+     * @param models key value pairs that to be expunged from the db.
+     * @throws Exception if data could not be expunged from the db.
      */
     void deleteBatch(Collection<Pair<Indexable, ? extends Class<? extends Persistable>>> models) throws Exception;
 

src/main/java/com/iota/iri/utils/collections/interfaces/UnIterableMap.java

@@ -3,7 +3,6 @@
 import java.util.Collection;
 import java.util.Map;
 
-
 /**
  * Similar to {@link Map} but hides key retrieval functionality.
  * Thus one can't iterate over key or entries.
@@ -14,50 +13,62 @@
  */
 public interface UnIterableMap<K,V> {
 
-
     /**
-     * {See {@link Map#size()}}
+     * @see Map#size()
+     * @return {@link Map#size()}
      */
     int size();
 
     /**
-     * {See {@link Map#isEmpty()}}
+     * @see Map#isEmpty()
+     * @return {@link Map#isEmpty()}
      */
     boolean isEmpty();
 
     /**
-     * {See {@link Map#containsKey(Object)}}
+     * @see Map#containsKey(Object)
+     * @param key {@link Map#containsKey(Object)}
+     * @return {@link Map#containsKey(Object)}
      */
     boolean containsKey(K key);
 
     /**
-     * {See {@link Map#containsValue(Object)}}
+     * @see Map#containsValue(Object)
+     * @param value {@link Map#containsValue(Object)}
+     * @return {@link Map#containsValue(Object)}
      */
     boolean containsValue(V value);
 
     /**
-     *
-     * {See {@link Map#get}}
+     * @see Map#get(Object)
+     * @param key {@link Map#get(Object)}
+     * @return {@link Map#get(Object)}
      */
     V get(K key);
 
     /**
-     * {See {@link Map#put}
+     * @see Map#put(Object, Object)
+     * @param key {@link Map#put(Object, Object)}
+     * @param value {@link Map#put(Object, Object)}
+     * @return {@link Map#put(Object, Object)}
      */
     V put(K key, V value);
 
     /**
-     * {See {@link Map#keySet()}}
+     * @see Map#remove(Object)
+     * @param key {@link Map#remove(Object)}
+     * @return {@link Map#remove(Object)}
      */
     V remove(K key);
 
     /**
-     * {See {@link Map#clear()}}
+     * @see Map#clear()
      */
     void clear();
 
     /**
-     * {See {@link Map#values}
+     * @see Map#values()
+     * @return {@link Map#values()}
      */
     Collection<V> values();
 }