[WIP] Fixing javadoc warnings #53

pom.xml

@@ -135,8 +135,15 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
+        <version>3.0.1</version>
         <configuration>
           <additionalparam>${javadoc.opts}</additionalparam>
+          <additionalJOptions>
+            <additionalJOption>-Xmaxerrs</additionalJOption>
+            <additionalJOption>1000</additionalJOption>
+            <additionalJOption>-Xmaxwarns</additionalJOption>
+            <additionalJOption>1000</additionalJOption>
+          </additionalJOptions>
         </configuration>
         <executions>
           <execution>
@@ -150,9 +157,17 @@
         </executions>
       </plugin>
 
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <version>3.1.0</version>
+      </plugin>
+
+
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-assembly-plugin</artifactId>
+        <version>3.1.0</version>
         <executions>
           <execution>
             <phase>package</phase>

src/main/java/de/tudarmstadt/ukp/jwktl/JWKTL.java

@@ -40,7 +40,7 @@
  */
 public class JWKTL {
 
-	/** Returns the software version. */
+	/** @return The software version as string. */
 	public static String getVersion() {
 		try {
 			Properties properties = new Properties();
@@ -59,40 +59,60 @@ public static String getVersion() {
 	/** Opens the parsed Wiktionary language edition stored at the given 
 	 *  locations and aggregated them in a {@link IWiktionaryCollection}. 
 	 *  This method uses a default cache size for the Berkeley DB.
-	 *  @throws WiktionaryException in case of any JWKTL-related error. */
+	 *  @param targetDirectories target directories with the parsed dumps.
+	 *  @throws WiktionaryException in case of any JWKTL-related error.
+	 *  @return Aggregated Wiktionary collection containing Wiktionary
+	 *  language editions stored at the given locations. 
+	 */
 	public static IWiktionaryCollection openCollection(
-			final File... parsedDumps) {
-		return openCollection(null, parsedDumps);
+			final File... targetDirectories) {
+		return openCollection(null, targetDirectories);
 	}
 
 	/** Opens the parsed Wiktionary language edition stored at the given 
 	 *  locations and aggregated them in a {@link IWiktionaryCollection}. 
 	 *  This method uses the given cache size for connecting to the 
 	 *  Berkeley DB.
-	 *  @throws WiktionaryException in case of any JWKTL-related error. */
+	 * 	@param cacheSize the memory (in Bytes) that is used as database
+	 *     cache, which can be used to speed up the DB access. Use
+	 *     null as a default value.
+	 *  @param targetDirectories target directories with the parsed dumps.
+	 *  @throws WiktionaryException in case of any JWKTL-related error.
+	 *  @return Aggregated and parsed Wiktionary language edition stored at the given 
+	 *  locations.
+	 */
 	public static IWiktionaryCollection openCollection(
-			final Long cacheSize, final File... parsedDumps) {
+			final Long cacheSize, final File... targetDirectories) {
 		IWiktionaryCollection result = new WiktionaryCollection();
-		for (File parsedDump : parsedDumps)
-			result.addEdition(openEdition(parsedDump, cacheSize));
+		for (File targetDirectory : targetDirectories)
+			result.addEdition(openEdition(targetDirectory, cacheSize));
 		return result;
 	}
 
 	/** Opens the parsed Wiktionary language edition stored at the given 
 	 *  location. This method uses a default cache size for the 
 	 *  Berkeley DB.
-	 *  @throws WiktionaryException in case of any JWKTL-related error. */
-	public static IWiktionaryEdition openEdition(final File parsedDump) {
-		return openEdition(parsedDump, null);
+	 *  @param targetDirectory target directory with the parsed dump.
+	 *  @throws WiktionaryException in case of any JWKTL-related error.
+	 *  @return Parsed Wiktionary language edition stored at the given location.
+	 */
+	public static IWiktionaryEdition openEdition(final File targetDirectory) {
+		return openEdition(targetDirectory, null);
 	}
 
 	/** Opens the parsed Wiktionary language edition stored at the given 
 	 *  location. This method uses the given cache size for connecting 
 	 *  to the Berkeley DB.
-	 *  @throws WiktionaryException in case of any JWKTL-related error. */
-	public static IWiktionaryEdition openEdition(final File parsedDump,
+	 *  @param targetDirectory target directory with the parsed dump.
+	 * 	@param cacheSize the memory (in Bytes) that is used as database
+	 *     cache, which can be used to speed up the DB access. Use
+	 *     null as a default value.
+	 *  @throws WiktionaryException in case of any JWKTL-related error.
+	 *  @return Parsed Wiktionary language edition stored at the given location.
+	 */
+	public static IWiktionaryEdition openEdition(final File targetDirectory,
 			final Long cacheSize) {
-		return new BerkeleyDBWiktionaryEdition(parsedDump, cacheSize);
+		return new BerkeleyDBWiktionaryEdition(targetDirectory, cacheSize);
 	}
 
 
@@ -142,9 +162,11 @@ public static void parseWiktionaryDump(final File dumpFile,
 
 	/** Deletes all files from a previously parsed Wiktionary from the
 	 *  specified directory. This method is equivalent to
-	 *  {@link BerkeleyDBWiktionaryEdition#deleteParsedWiktionary(File)}. */
-	public static void deleteEdition(final File parsedData) {
-		BerkeleyDBWiktionaryEdition.deleteParsedWiktionary(parsedData);
+	 *  {@link BerkeleyDBWiktionaryEdition#deleteParsedWiktionary(File)}.
+	 *  @param targetDirectory target directory with the parsed dump.
+	 */
+	public static void deleteEdition(final File targetDirectory) {
+		BerkeleyDBWiktionaryEdition.deleteParsedWiktionary(targetDirectory);
 	}
 
 }

src/main/java/de/tudarmstadt/ukp/jwktl/WiktionaryCli.java

@@ -19,6 +19,7 @@
 
 import java.io.BufferedReader;
 import java.io.File;
+import java.io.IOException;
 import java.io.InputStreamReader;
 
 import de.tudarmstadt.ukp.jwktl.api.IWiktionaryEdition;
@@ -34,8 +35,9 @@ public class WiktionaryCli {
 
 	/**
 	 * @param args path to parsed Wiktionary data
+	 * @throws IOException in case system input cannot be read.
 	 */
-	public static void main(String[] args) throws Exception {
+	public static void main(String[] args) throws IOException {
 		if (args.length != 1)
 			throw new IllegalArgumentException("Too few arguments. "
 						+ "Required arguments: <PARSED-WIKTIONARY>");

src/main/java/de/tudarmstadt/ukp/jwktl/api/IPronunciation.java

@@ -43,19 +43,19 @@ enum PronunciationType {
 		RAW
 	}
 
-	/** Returns the type of this pronunciation, which can be audio files 
+	/** @return The type of this pronunciation, which can be audio files 
 	 *  or a specific notation schema used to represent pronunciation 
 	 *  information. */
 	PronunciationType getType();
 
-	/** The representation of the pronunciation using a standardized
+	/** @return The representation of the pronunciation using a standardized
 	 *  notation such as IPA. In case of audio files, the file name of
 	 *  the sound file is returned. The corresponding URL of this sound file
 	 *  needs to be obtained by querying 
 	 *  http://[LANGUAGE].wiktionary.org/wiki/File:[FILENAME]. */
 	String getText();
 
-	/** Returns additional information for this pronunciation, such as 
+	/** @return Additional information for this pronunciation, such as 
 	 *  a geographical reference. */
 	String getNote();
 

src/main/java/de/tudarmstadt/ukp/jwktl/api/IQuotation.java

@@ -27,10 +27,10 @@
  */
 public interface IQuotation {
 
-	/** Returns the source of the quotation. */
+	/** @return The source of the quotation. */
 	IWikiString getSource();
 
-	/** Returns the text of the quotation as a list of {@link IWikiString}s. */
+	/** @return The text of the quotation as a list of {@link IWikiString}s. */
 	List<IWikiString> getLines();
 
 }

src/main/java/de/tudarmstadt/ukp/jwktl/api/IWikiString.java

@@ -30,20 +30,24 @@
  */
 public interface IWikiString {
 
-	/** Returns the original text including all wiki markup. */
+	/** @return The original text including all wiki markup. */
 	String getText();
 
 	/** Parses the original text to filter out all wiki markup and thus
 	 *  returns a human-readable version of the text. Note that the parsing 
 	 *  might be done on demand, so avoid invoking this method repeatedly
-	 *  for the same text. */
+	 *  for the same text.
+	 *  @return A human-readable version of the text.
+	 */
 	String getPlainText();
 
 	/** Returns a list of wiki-internal links. That is, all substrings
 	 *  enclosed by two square brackets. Link captions will be removed.
 	 *  If no wiki links are found, an empty list will be returned. Note that 
 	 *  the parsing might be done on demand, so avoid invoking this method 
-	 *  repeatedly for the same text. */
+	 *  repeatedly for the same text.
+	 *  @return A list of wiki-internal links.
+	 */
 	List<String> getWikiLinks();
 
 	/* Returns a list of external links. That is, all valid URLs in the