Merge pull request #62 from informatik-ag-ngl/f/javadoc

Added and fixed existing Javadoc, configured Javadoc validation

.classpath

@@ -28,5 +28,11 @@
 			<attribute name="maven.pomderived" value="true"/>
 		</attributes>
 	</classpathentry>
+	<classpathentry excluding="**" kind="src" output="target/test-classes" path="src/test/resources">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="test" value="true"/>
+		</attributes>
+	</classpathentry>
 	<classpathentry kind="output" path="target/classes"/>
 </classpath>

.settings/org.eclipse.jdt.core.prefs

@@ -8,10 +8,18 @@ org.eclipse.jdt.core.compiler.annotation.nonnullbydefault.secondary=
 org.eclipse.jdt.core.compiler.annotation.nullable=org.eclipse.jdt.annotation.Nullable
 org.eclipse.jdt.core.compiler.annotation.nullable.secondary=
 org.eclipse.jdt.core.compiler.annotation.nullanalysis=disabled
+org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
+org.eclipse.jdt.core.compiler.codegen.methodParameters=do not generate
 org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.8
+org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
 org.eclipse.jdt.core.compiler.compliance=1.8
+org.eclipse.jdt.core.compiler.debug.lineNumber=generate
+org.eclipse.jdt.core.compiler.debug.localVariable=generate
+org.eclipse.jdt.core.compiler.debug.sourceFile=generate
+org.eclipse.jdt.core.compiler.doc.comment.support=enabled
 org.eclipse.jdt.core.compiler.problem.APILeak=warning
 org.eclipse.jdt.core.compiler.problem.annotationSuperInterface=warning
+org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
 org.eclipse.jdt.core.compiler.problem.autoboxing=ignore
 org.eclipse.jdt.core.compiler.problem.comparingIdentical=warning
 org.eclipse.jdt.core.compiler.problem.deadCode=warning
@@ -21,6 +29,7 @@ org.eclipse.jdt.core.compiler.problem.deprecationWhenOverridingDeprecatedMethod=
 org.eclipse.jdt.core.compiler.problem.discouragedReference=warning
 org.eclipse.jdt.core.compiler.problem.emptyStatement=ignore
 org.eclipse.jdt.core.compiler.problem.enablePreviewFeatures=disabled
+org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
 org.eclipse.jdt.core.compiler.problem.explicitlyClosedAutoCloseable=ignore
 org.eclipse.jdt.core.compiler.problem.fallthroughCase=ignore
 org.eclipse.jdt.core.compiler.problem.fatalOptionalError=disabled
@@ -33,12 +42,25 @@ org.eclipse.jdt.core.compiler.problem.includeNullInfoFromAsserts=disabled
 org.eclipse.jdt.core.compiler.problem.incompatibleNonInheritedInterfaceMethod=warning
 org.eclipse.jdt.core.compiler.problem.incompleteEnumSwitch=ignore
 org.eclipse.jdt.core.compiler.problem.indirectStaticAccess=ignore
+org.eclipse.jdt.core.compiler.problem.invalidJavadoc=info
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTags=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsDeprecatedRef=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsNotVisibleRef=enabled
+org.eclipse.jdt.core.compiler.problem.invalidJavadocTagsVisibility=public
 org.eclipse.jdt.core.compiler.problem.localVariableHiding=ignore
 org.eclipse.jdt.core.compiler.problem.methodWithConstructorName=warning
 org.eclipse.jdt.core.compiler.problem.missingDefaultCase=ignore
 org.eclipse.jdt.core.compiler.problem.missingDeprecatedAnnotation=ignore
 org.eclipse.jdt.core.compiler.problem.missingEnumCaseDespiteDefault=disabled
 org.eclipse.jdt.core.compiler.problem.missingHashCodeMethod=ignore
+org.eclipse.jdt.core.compiler.problem.missingJavadocComments=info
+org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsOverriding=disabled
+org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsVisibility=public
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=all_standard_tags
+org.eclipse.jdt.core.compiler.problem.missingJavadocTags=info
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsMethodTypeParameters=disabled
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsOverriding=disabled
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagsVisibility=public
 org.eclipse.jdt.core.compiler.problem.missingOverrideAnnotation=ignore
 org.eclipse.jdt.core.compiler.problem.missingOverrideAnnotationForInterfaceMethodImplementation=enabled
 org.eclipse.jdt.core.compiler.problem.missingSerialVersion=warning
@@ -61,8 +83,8 @@ org.eclipse.jdt.core.compiler.problem.potentiallyUnclosedCloseable=ignore
 org.eclipse.jdt.core.compiler.problem.rawTypeReference=warning
 org.eclipse.jdt.core.compiler.problem.redundantNullAnnotation=warning
 org.eclipse.jdt.core.compiler.problem.redundantNullCheck=ignore
-org.eclipse.jdt.core.compiler.problem.redundantSpecificationOfTypeArguments=ignore
+org.eclipse.jdt.core.compiler.problem.redundantSpecificationOfTypeArguments=warning
-org.eclipse.jdt.core.compiler.problem.redundantSuperinterface=ignore
+org.eclipse.jdt.core.compiler.problem.redundantSuperinterface=warning
 org.eclipse.jdt.core.compiler.problem.reportMethodCanBePotentiallyStatic=ignore
 org.eclipse.jdt.core.compiler.problem.reportMethodCanBeStatic=ignore
 org.eclipse.jdt.core.compiler.problem.reportPreviewFeatures=ignore
@@ -74,7 +96,7 @@ org.eclipse.jdt.core.compiler.problem.syntacticNullAnalysisForFields=disabled
 org.eclipse.jdt.core.compiler.problem.syntheticAccessEmulation=ignore
 org.eclipse.jdt.core.compiler.problem.terminalDeprecation=warning
 org.eclipse.jdt.core.compiler.problem.typeParameterHiding=warning
-org.eclipse.jdt.core.compiler.problem.unavoidableGenericTypeProblems=enabled
+org.eclipse.jdt.core.compiler.problem.unavoidableGenericTypeProblems=disabled
 org.eclipse.jdt.core.compiler.problem.uncheckedTypeOperation=warning
 org.eclipse.jdt.core.compiler.problem.unclosedCloseable=warning
 org.eclipse.jdt.core.compiler.problem.undocumentedEmptyBlock=ignore
@@ -95,7 +117,7 @@ org.eclipse.jdt.core.compiler.problem.unusedImport=warning
 org.eclipse.jdt.core.compiler.problem.unusedLabel=warning
 org.eclipse.jdt.core.compiler.problem.unusedLocal=warning
 org.eclipse.jdt.core.compiler.problem.unusedObjectAllocation=ignore
-org.eclipse.jdt.core.compiler.problem.unusedParameter=ignore
+org.eclipse.jdt.core.compiler.problem.unusedParameter=warning
 org.eclipse.jdt.core.compiler.problem.unusedParameterIncludeDocCommentReference=enabled
 org.eclipse.jdt.core.compiler.problem.unusedParameterWhenImplementingAbstract=disabled
 org.eclipse.jdt.core.compiler.problem.unusedParameterWhenOverridingConcrete=disabled

src/main/java/envoy/client/Chat.java

@@ -7,6 +7,19 @@ import javax.swing.DefaultListModel;
 import envoy.schema.Message;
 import envoy.schema.User;
 
+/**
+ * Represents a chat between two {@link User}s <br>
+ * as a list of {@link Message} objects.
+ * <br>
+ * Project: <strong>envoy-client</strong><br>
+ * File: <strong>Chat.java</strong><br>
+ * Created: <strong>19 Oct 2019</strong><br>
+ *
+ * @author Maximilian K&auml;fer
+ * @author Leon Hofmeister
+ * @author Kai S. K. Engelbart
+ * @since Envoy v0.1-alpha
+ */
 public class Chat implements Serializable {
 
 	private static final long serialVersionUID = -7751248474547242056L;

src/main/java/envoy/client/Config.java

@@ -6,6 +6,11 @@ import java.util.Properties;
 import envoy.exception.EnvoyException;
 
 /**
+ * Manages all application settings that are set during application startup by
+ * either loading them from the {@link Properties} file
+ * {@code client.properties} or parsing them from the command line arguments of
+ * the application.<br>
+ * <br>
  * Project: <strong>envoy-client</strong><br>
  * File: <strong>Config.java</strong><br>
  * Created: <strong>12 Oct 2019</strong><br>
@@ -24,6 +29,10 @@ public class Config {
 
 	private Config() {}
 
+	/**
+	 * @return the singleton instance of the {@link Config}
+	 * @since Envoy v0.1-alpha
+	 */
 	public static Config getInstance() {
 		if (config == null) config = new Config();
 		return config;
@@ -143,5 +152,4 @@ public class Config {
 	 * @since Envoy v0.1-alpha
 	 */
 	public void setSyncTimeout(int syncTimeout) { this.syncTimeout = syncTimeout; }
-
 }

src/main/java/envoy/client/LocalDB.java

@@ -56,7 +56,7 @@ public class LocalDB {
 	 * system, call {@link LocalDB#initializeDBFile()}.
 	 *
 	 * @param localDBDir the directory in which to store users and chats
-	 * @throws IOException if the LocalDB could not be initialised
+	 * @throws IOException if the LocalDB could not be initialized
 	 * @since Envoy v0.1-alpha
 	 */
 	public LocalDB(File localDBDir) throws IOException {

src/main/java/envoy/client/Settings.java

@@ -14,6 +14,10 @@ import java.util.prefs.Preferences;
 import envoy.client.ui.Theme;
 
 /**
+ * Manages all application settings, which are different objects that can be
+ * changed during runtime and serialized them by using either the file system or
+ * the {@link Preferences} API.<br>
+ * <br>
  * Project: <strong>envoy-client</strong><br>
  * File: <strong>Settings.java</strong><br>
  * Created: <strong>11 Nov 2019</strong><br>
@@ -88,7 +92,8 @@ public class Settings {
 	/**
 	 * Updates the preferences when the save button is clicked.
 	 *
-	 * @throws IOException if something went wrong while saving
+	 * @throws IOException if an error occurs while saving the themes to the theme
+	 *                     file
 	 * @since Envoy v0.2-alpha
 	 */
 	public void save() throws IOException {
@@ -103,56 +108,55 @@ public class Settings {
 	}
 
 	/**
-	 * adds new theme to the theme map and sets current theme to the new theme.
+	 * Adds new theme to the theme map.
 	 *
-	 * @param theme the theme to add
+	 * @param theme the {@link Theme} to add
 	 * @since Envoy v0.2-alpha
 	 */
-	public void addNewThemeToMap(Theme theme) {
+	public void addNewThemeToMap(Theme theme) { settings.getThemes().put(theme.getThemeName(), theme); }
-		settings.getThemes().put(theme.getThemeName(), theme);
-		// currentTheme = theme.getThemeName();
-	}
 
 	/**
-	 * @return the name of the current theme
+	 * @return the name of the currently active {@link Theme}
 	 * @since Envoy v0.2-alpha
 	 */
 	public String getCurrentTheme() { return currentTheme; }
 
 	/**
-	 * Sets the currentTheme
+	 * Sets the name of the current {@link Theme}.
 	 *
-	 * @param themeName the name of the new current theme
+	 * @param themeName the name to set
 	 * @since Envoy v0.2-alpha
 	 */
 	public void setCurrentTheme(String themeName) { currentTheme = themeName; }
 
 	/**
-	 * @return true, if "enter" suffices to send a message, else it has to be "ctrl"
+	 * @return {@code true}, if pressing the {@code Enter} key suffices to send a
-	 *         + "enter"
+	 *         message. Otherwise it has to be pressed in conjunction with the
+	 *         {@code Control} key.
 	 * @since Envoy v0.2-alpha
 	 */
 	public boolean isEnterToSend() { return enterToSend; }
 
 	/**
-	 * Change mode of posting a message via Keystroke.
+	 * Changes the keystrokes performed by the user to send a message.
 	 *
-	 * @param enterToSend if true, "enter" suffices to send a message, <br>
+	 * @param enterToSend If set to {@code true} a message can be sent by pressing
-	 *                    else it has to be "ctrl" + "enter"
+	 *                    the {@code Enter} key. Otherwise it has to be pressed in
+	 *                    conjunction with the {@code Control} key.
 	 * @since Envoy v0.2-alpha
 	 */
 	public void setEnterToSend(boolean enterToSend) { this.enterToSend = enterToSend; }
 
 	/**
-	 * @return the map of all themes 
+	 * @return a {@code Map<String, Theme>} of all themes with their names as keys
 	 * @since Envoy v0.2-alpha
 	 */
 	public Map<String, Theme> getThemes() { return themes; }
 
 	/**
-	 * Sets the map of all themes
+	 * Sets the {@code Map<String, Theme>} of all themes with their names as keys
 	 *
-	 * @param themes a map(String, Theme) of all themes
+	 * @param themes the theme map to set
 	 * @since Envoy v0.2-alpha
 	 */
 	public void setThemes(Map<String, Theme> themes) { this.themes = themes; }

src/main/java/envoy/client/event/MessageEvent.java

@@ -13,6 +13,13 @@ public class MessageEvent implements Event<Message> {
 
 	protected final Message message;
 
+	/**
+	 * Initializes a {@link MessageEvent} conveying information about a
+	 * {@link Message} object.
+	 *
+	 * @param message the {@link Message} object to attach to this event
+	 * @since Envoy v0.2-alpha
+	 */
 	public MessageEvent(Message message) { this.message = message; }
 
 	@Override

src/main/java/envoy/client/event/ThemeChangeEvent.java

@@ -8,11 +8,19 @@ import envoy.client.ui.Theme;
  * Created: <strong>15 Dec 2019</strong><br>
  *
  * @author Kai S. K. Engelbart
+ * @since Envoy v0.2-alpha
  */
 public class ThemeChangeEvent implements Event<Theme> {
 
 	private final Theme theme;
 
+	/**
+	 * Initializes a {@link ThemeChangeEvent} conveying information about the change
+	 * of the {@link Theme} currently in use
+	 *
+	 * @param theme the new currently used {@link Theme} object
+	 * @since Envoy v0.2-alpha
+	 */
 	public ThemeChangeEvent(Theme theme) { this.theme = theme; }
 
 	@Override

src/main/java/envoy/client/ui/ChatWindow.java

@@ -66,6 +66,14 @@ public class ChatWindow extends JFrame {
 
 	private static final Logger logger = EnvoyLog.getLogger(ChatWindow.class.getSimpleName());
 
+	/**
+	 * Initializes a {@link JFrame} with UI elements used to send and read messages
+	 * to different users.
+	 *
+	 * @param client  the {@link Client} used to send and receive messages
+	 * @param localDB the {@link LocalDB} used to manage stored messages and users
+	 * @since Envoy v0.1-alpha
+	 */
 	public ChatWindow(Client client, LocalDB localDB) {
 		this.client		= client;
 		this.localDB	= localDB;
@@ -112,9 +120,8 @@ public class ChatWindow extends JFrame {
 			@Override
 			public void keyReleased(KeyEvent e) {
 				if (e.getKeyCode() == KeyEvent.VK_ENTER
-						&& ((Settings.getInstance().isEnterToSend() && e.getModifiersEx() == 0) || (e.getModifiersEx() == KeyEvent.CTRL_DOWN_MASK))) {
+						&& ((Settings.getInstance().isEnterToSend() && e.getModifiersEx() == 0) || (e.getModifiersEx() == KeyEvent.CTRL_DOWN_MASK)))
 					postMessage(messageList);
-				}
 			}
 		});
 
@@ -219,8 +226,8 @@ public class ChatWindow extends JFrame {
 
 	/**
 	 * Used to immediately reload the ChatWindow when settings were changed.
-     *
+	 *
-     * @param theme the theme to change colors into
+	 * @param theme the theme to change colors into
 	 * @since Envoy v0.1-alpha
 	 */
 	private void changeChatWindowColors(Theme theme) {

src/main/java/envoy/client/ui/MessageListRenderer.java

@@ -14,7 +14,6 @@ import envoy.schema.Message;
 /**
  * Defines how a message is displayed.<br>
  * <br>
- * 
  * Project: <strong>envoy-client</strong><br>
  * File: <strong>UserListRenderer.java</strong><br>
  * Created: <strong>19 Oct 2019</strong><br>
@@ -62,7 +61,7 @@ public class MessageListRenderer extends JLabel implements ListCellRenderer<Mess
 		return this;
 	}
 
-	public String toHex(Color c) {
+	private String toHex(Color c) {
 		int		r	= c.getRed();
 		int		g	= c.getGreen();
 		int		b	= c.getBlue();

src/main/java/envoy/client/ui/Startup.java

@@ -32,6 +32,17 @@ public class Startup {
 
 	private static final Logger logger = EnvoyLog.getLogger(Startup.class.getSimpleName());
 
+	/**
+	 * Loads the application by first loading the configuration, then acquiring a
+	 * user name and connecting to the server. If the server cannot be reached,
+	 * offline mode is entered if possible. After that, a {@link ChatWindow}
+	 * instance is initialized and then displayed to the user. Upon application
+	 * exit, settings and the local database are saved.
+	 *
+	 * @param args the command line arguments may contain configuration parameters
+	 *             and are parsed by the {@link Config} class
+	 * @since Envoy v0.1-alpha
+	 */
 	public static void main(String[] args) {
 		Config config = Config.getInstance();
 

src/main/java/envoy/client/ui/Theme.java

@@ -26,6 +26,23 @@ public class Theme implements Serializable {
 	private Color	selectionColor;
 	private Color	typingMessageColor;
 
+	/**
+	 * Initializes a {@link Theme} with all colors relevant to the application GUI.
+	 *
+	 * @param themeName                   the name of the {@link Theme}
+	 * @param backgroundColor             the background color
+	 * @param cellColor                   the cell color
+	 * @param interactableForegroundColor the color of interactable foreground UI
+	 *                                    elements
+	 * @param interactableBackgroundColor the color of interactable background UI
+	 *                                    elements
+	 * @param messageColorChat            the color of chat messages
+	 * @param dateColorChat               the color of chat message metadata
+	 * @param selectionColor              the section color
+	 * @param typingMessageColor          the color of currently typed messages
+	 * @param userNameColor               the color of user names
+	 * @since Envoy v0.2-alpha
+	 */
 	public Theme(String themeName, Color backgroundColor, Color cellColor, Color interactableForegroundColor, Color interactableBackgroundColor,
 			Color messageColorChat, Color dateColorChat, Color selectionColor, Color typingMessageColor, Color userNameColor) {
 
@@ -42,6 +59,14 @@ public class Theme implements Serializable {
 		this.userNameColor					= userNameColor;
 	}
 
+	/**
+	 * Initializes a {@link Theme} by copying all parameters except for the name
+	 * from another {@link Theme} instance.
+	 *
+	 * @param name  the name of the {@link Theme}
+	 * @param other the {@link Theme} to copy
+	 * @since Envoy v0.2-alpha
+	 */
 	public Theme(String name, Theme other) {
 		this(name, other.backgroundColor, other.cellColor, other.interactableForegroundColor,
 				other.interactableBackgroundColor, other.messageColorChat, other.dateColorChat, other.selectionColor,
@@ -129,31 +154,31 @@ public class Theme implements Serializable {
 	public void setColor(int index, Color newColor) {
 		switch (index) {
 			case 0:
-				this.backgroundColor = newColor;
+				backgroundColor = newColor;
 				break;
 			case 1:
-				this.cellColor = newColor;
+				cellColor = newColor;
 				break;
 			case 2:
-				this.interactableForegroundColor = newColor;
+				interactableForegroundColor = newColor;
 				break;
 			case 3:
-				this.interactableBackgroundColor = newColor;
+				interactableBackgroundColor = newColor;
 				break;
 			case 4:
-				this.messageColorChat = newColor;
+				messageColorChat = newColor;
 				break;
 			case 5:
-				this.dateColorChat = newColor;
+				dateColorChat = newColor;
 				break;
 			case 6:
-				this.selectionColor = newColor;
+				selectionColor = newColor;
 				break;
 			case 7:
-				this.typingMessageColor = newColor;
+				typingMessageColor = newColor;
 				break;
 			case 8:
-				this.userNameColor = newColor;
+				userNameColor = newColor;
 				break;
 		}
 	}

src/main/java/envoy/client/ui/UserListRenderer.java

@@ -58,7 +58,7 @@ public class UserListRenderer extends JLabel implements ListCellRenderer<User> {
 		return this;
 	}
 
-	public String toHex(Color c) {
+	private String toHex(Color c) {
 		int		r	= c.getRed();
 		int		g	= c.getGreen();
 		int		b	= c.getBlue();