Squashed CheckStyle warnings, mostly JavaDoc.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@279439 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 56 insertions, 20 deletions

diff --git a/src/java/org/apache/fop/apps/FOPException.java b/src/java/org/apache/fop/apps/FOPException.java
index 569a025f1..5a496bd67 100644
--- a/src/java/org/apache/fop/apps/FOPException.java
+++ b/src/java/org/apache/fop/apps/FOPException.java
@@ -33,14 +33,20 @@ public class FOPException extends SAXException {
     private int column;
 
     /**
-     * create a new FOP Exception
-     *
-     * @param message descriptive message
+     * Constructs a new FOP exception with the specified detail message.
+     * @param message the detail message.
      */
     public FOPException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new FOP exception with the specified detail message and location.
+     * @param message the detail message
+     * @param systemId the system id of the FO document which is associated with the exception. May be null.
+     * @param line line number in the FO document which is associated with the exception.
+     * @param column clolumn number in the line which is associated with the exception.
+     */
     public FOPException(String message, String systemId, int line, int column) {
         super(message);
         this.systemId = systemId;
@@ -48,6 +54,11 @@ public class FOPException extends SAXException {
         this.column = column;
     }
 
+    /**
+     * Constructs a new FOP exception with the specified detail message and location.
+     * @param message the detail message.
+     * @param locator the locator holding the location.
+     */
     public FOPException(String message, Locator locator) {
         super(message);
         setLocator(locator);
@@ -55,22 +66,26 @@ public class FOPException extends SAXException {
 
 
     /**
-     *
-     * @param e Throwable object
+     * Constructs a new FOP exception with the specified cause.
+     * @param cause the cause.
      */
-    public FOPException(Exception e) {
-        super(e);
+    public FOPException(Exception cause) {
+        super(cause);
     }
 
     /**
-     *
-     * @param message descriptive message
-     * @param e Throwable object
+     * Constructs a new exception with the specified detail message and cause.
+     * @param message  the detail message
+     * @param cause the cause 
      */
-    public FOPException(String message, Throwable e) {
-        super(message);
+    public FOPException(String message, Exception cause) {
+        super(message, cause);
     }
 
+    /**
+     * Set a location associated with the exception.
+     * @param location the locator holding the location.
+     */
     public void setLocator(Locator locator) {
         if (locator != null) {
             this.systemId = locator.getSystemId();
@@ -79,19 +94,40 @@ public class FOPException extends SAXException {
         }
     }
 
+    /**
+     * Set a location associated with the exception.
+     * @param systemId the system id of the FO document which is associated with the exception. May be null.
+     * @param line line number in the FO document which is associated with the exception.
+     * @param column clolumn number in the line which is associated with the exception.
+     */
     public void setLocation(String systemId, int line, int column) {
         this.systemId = systemId;
         this.line = line;
         this.column = column;
     }
 
+    /**
+     * Indicate whether a location was set.
+     */
     public boolean isLocationSet() {
+        // TODO: this is actually a dangerous assumption: A line
+        // number of 0 or -1 might be used to indicate an unknown line
+        // number, while the system ID might still be of use.
         return line > 0;
     }
 
+    /**
+     * Returns the detail message string of this FOP exception.
+     * If a location was set, the message is prepended with it in the
+     * form
+     * <pre>
+     *  SystemId:LL:CC: &amp;the message&amp;
+     * </pre>
+     * (the format used by most GNU tools)
+     */
     public String getMessage() {
         if (isLocationSet()) {
-            return systemId + ":" + line + "," + column + " " + super.getMessage();
+            return systemId + ":" + line + ":" + column + ": " + super.getMessage();
         } else {
             return super.getMessage();
         }
@@ -108,8 +144,8 @@ public class FOPException extends SAXException {
             result = ((SAXException)result).getException();
         }
         if (result instanceof java.lang.reflect.InvocationTargetException) {
-            result =
-                ((java.lang.reflect.InvocationTargetException)result).getTargetException();
+            result
+                = ((java.lang.reflect.InvocationTargetException)result).getTargetException();
         }
         if (result != getException()) {
             return result;
@@ -118,7 +154,7 @@ public class FOPException extends SAXException {
     }
 
     /**
-     * Write stack trace to stderr
+     * Prints this FOP exception and its backtrace to the standard error stream.
      */
     public void printStackTrace() {
         synchronized (System.err) {
@@ -135,8 +171,8 @@ public class FOPException extends SAXException {
     }
 
     /**
-     * write stack trace on a PrintStream
-     * @param stream PrintStream on which to write stack trace
+     * Prints this FOP exception and its backtrace to the specified print stream.
+     * @param stream PrintStream to use for output
      */
     public void printStackTrace(java.io.PrintStream stream) {
         synchronized (stream) {
@@ -153,8 +189,8 @@ public class FOPException extends SAXException {
     }
 
     /**
-     * Write stack trace on a PrintWriter
-     * @param writer PrintWriter on which to write stack trace
+     * Prints this FOP exception and its backtrace to the specified print writer.
+     * @param writer PrintWriter to use for output
      */
     public void printStackTrace(java.io.PrintWriter writer) {
         synchronized (writer) {