GUACAMOLE-364: addressed various documentation issues

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationFailureListener.java

@@ -28,7 +28,7 @@ import org.apache.guacamole.net.event.AuthenticationFailureEvent;
  * be used to cancel the authentication failure.
  *
  * @deprecated
- *      Listeners should instead implement the {@link Listener} interface
+ *      Listeners should instead implement the {@link Listener} interface.
  */
 @Deprecated
 public interface AuthenticationFailureListener {
@@ -37,12 +37,15 @@ public interface AuthenticationFailureListener {
      * Event hook which fires immediately after a user's authentication attempt
      * fails.
      *
-     * @param e The AuthenticationFailureEvent describing the authentication
-     *          failure that just occurred.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            authentication failure event. Note that
-     *                            throwing an exception will NOT cause the
-     *                            authentication failure to be canceled.
+     * @param e
+     *      The AuthenticationFailureEvent describing the authentication
+     *      failure that just occurred.
+     *
+     * @throws GuacamoleException
+     *      If an error occurs while handling the authentication failure event.
+     *      Note that throwing an exception will NOT cause the authentication
+     *      failure to be canceled (which makes no sense), but it will prevent
+     *      subsequent listeners from receiving the notification.
      */
     void authenticationFailed(AuthenticationFailureEvent e)
             throws GuacamoleException;

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/AuthenticationSuccessListener.java

@@ -39,15 +39,18 @@ public interface AuthenticationSuccessListener {
      * succeeds. The return value of this hook dictates whether the
      * successful authentication attempt is canceled.
      *
-     * @param e The AuthenticationFailureEvent describing the authentication
-     *          failure that just occurred.
-     * @return true if the successful authentication attempt should be
-     *         allowed, or false if the attempt should be denied, causing
-     *         the attempt to effectively fail.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            authentication success event. Throwing an
-     *                            exception will also cancel the authentication
-     *                            success.
+     * @param e
+     *      The AuthenticationFailureEvent describing the authentication
+     *      failure that just occurred.
+     *
+     * @return
+     *      true if the successful authentication attempt should be
+     *      allowed, or false if the attempt should be denied, causing
+     *      the attempt to effectively fail.
+     *
+     * @throws GuacamoleException
+     *      If an error occurs while handling the authentication success event.
+     *      Throwing an exception will also cancel the authentication success.
      */
     boolean authenticationSucceeded(AuthenticationSuccessEvent e)
             throws GuacamoleException;

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/Listener.java

@@ -39,12 +39,12 @@ public interface Listener {
      * details.
      *
      * @param event
-     *     an object that describes the subject event
+     *     An object that describes the event that has occurred.
      *
      * @throws GuacamoleException
      *     If the listener wishes to stop notification of the event to subsequent
      *     listeners. For some event types, this acts to veto an action in progress;
-     *     e.g. treating a successful authentication as though it failed
+     *     e.g. treating a successful authentication as though it failed.
      */
     void handleEvent(Object event) throws GuacamoleException;
 

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelCloseListener.java

@@ -27,7 +27,7 @@ import org.apache.guacamole.net.event.TunnelCloseEvent;
  * existing tunnel is closed.
  *
  * @deprecated
- *      Listeners should instead implement the {@link Listener} interface
+ *      Listeners should instead implement the {@link Listener} interface.
  */
 @Deprecated
 public interface TunnelCloseListener {
@@ -37,16 +37,19 @@ public interface TunnelCloseListener {
      * The return value of this hook dictates whether the tunnel is allowed to
      * be closed.
      *
-     * @param e The TunnelCloseEvent describing the tunnel being closed and
-     *          any associated credentials.
-     * @return true if the tunnel should be allowed to be closed, or false
-     *         if the attempt should be denied, causing the attempt to
-     *         effectively fail.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            tunnel close event. Throwing an exception
-     *                            will also stop the tunnel from being closed.
+     * @param e
+     *      The TunnelCloseEvent describing the tunnel being closed and
+     *      any associated credentials.
+     *
+     * @return
+     *      true if the tunnel should be allowed to be closed, or false
+     *      if the attempt should be denied, causing the attempt to
+     *      effectively fail.
+     *
+     * @throws GuacamoleException
+     *      If an error occurs while handling the tunnel close event. Throwing
+     *      an exception will also stop the tunnel from being closed.
      */
-    boolean tunnelClosed(TunnelCloseEvent e)
-            throws GuacamoleException;
+    boolean tunnelClosed(TunnelCloseEvent e) throws GuacamoleException;
 
 }

guacamole-ext/src/main/java/org/apache/guacamole/net/event/listener/TunnelConnectListener.java

@@ -27,27 +27,30 @@ import org.apache.guacamole.net.event.TunnelConnectEvent;
  * tunnel is connected.
  *
  * @deprecated
- *      Listeners should instead implement the {@link Listener} interface
+ *      Listeners should instead implement the {@link Listener} interface.
  */
 @Deprecated
 public interface TunnelConnectListener {
 
    /**
-     * Event hook which fires immediately after a new tunnel is connected.
-     * The return value of this hook dictates whether the tunnel is made visible
-     * to the session.
-     *
-     * @param e The TunnelConnectEvent describing the tunnel being connected and
-     *          any associated credentials.
-     * @return true if the tunnel should be allowed to be connected, or false
-     *         if the attempt should be denied, causing the attempt to
-     *         effectively fail.
-     * @throws GuacamoleException If an error occurs while handling the
-     *                            tunnel connect event. Throwing an exception
-     *                            will also stop the tunnel from being made
-     *                            visible to the session.
-     */
-    boolean tunnelConnected(TunnelConnectEvent e)
-            throws GuacamoleException;
+    * Event hook which fires immediately after a new tunnel is connected.
+    * The return value of this hook dictates whether the tunnel is made visible
+    * to the session.
+    *
+    * @param e
+    *      The TunnelConnectEvent describing the tunnel being connected and
+    *      any associated credentials.
+    *
+    * @return
+    *      true if the tunnel should be allowed to be connected, or false
+    *      if the attempt should be denied, causing the attempt to
+    *      effectively fail.
+    *
+    * @throws GuacamoleException
+    *       If an error occurs while handling the tunnel connect event. Throwing
+    *       an exception will also stop the tunnel from being made visible to the
+    *       session.
+    */
+    boolean tunnelConnected(TunnelConnectEvent e) throws GuacamoleException;
 
 }