[cp-patches] [FYI]: API docs additions for javax.print

[Wolfgang Baer]

Hi,

this patch adds class and method documentation to the
javax.print exception stuff.

Regards,
Wolfgang

2005-12-30  Wolfgang Baer  <address@hidden>

        * javax/print/AttributeException.java,
        * javax/print/URIException.java,
        * javax/print/FlavorException.java,
        * javax/print/PrintException.java,
        Added and updated javadocs to class and methods.


Index: javax/print/AttributeException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/AttributeException.java,v
retrieving revision 1.2
diff -u -r1.2 AttributeException.java
--- javax/print/AttributeException.java 2 Jul 2005 20:32:45 -0000       1.2
+++ javax/print/AttributeException.java 30 Dec 2005 14:51:35 -0000
@@ -1,5 +1,5 @@
-/* CancelablePrintJob.java --
-   Copyright (C) 2004 Free Software Foundation, Inc.
+/* AttributeException.java --
+   Copyright (C) 2004, 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,23 +41,36 @@
 import javax.print.attribute.Attribute;
 
 /**
+ * <code>AttributeException</code> specifies two methods a specific
+ * subclass of address@hidden javax.print.PrintException} may implement to
+ * provide further information of printing errors if unsupported
+ * attribute classes or values of attributes are involved.
+ * <p>
+ * There exists no <code>PrintException</code> class implementing this 
+ * interface. Providing these extensions in <code>PrintException</code> 
+ * subclasses is left to the concrete print service implementation. 
+ * </p> 
+ * 
  * @author Michael Koch (address@hidden)
  */
 public interface AttributeException
 {
   /**
    * Returns the unsupported printing attribute classes for a print service
-   * that does not support them.
+   * that does not support the attribute category at all. The returned 
+   * class instances are sublcasses of the base interface address@hidden 
Attribute}.
    * 
-   * @return array of unsupported attribute classes, or null
+   * @return The unsupported attribute classes, or <code>null</code> if there
+   * are no such attribute classes.
    */
   Class[] getUnsupportedAttributes();
   
   /**
-   * Returns the unsupported values of printing attributes for a print service
-   * that does not support them.
+   * Returns the unsupported attribute values of printing attributes a specific
+   * print service does support but not the particular provided value.
    *   
-   * @return array of unsupperted attribute values, or null
+   * @return The unsupported attribute values, or <code>null</code> if there
+   * are no such attributes values.
    */
   Attribute[] getUnsupportedValues();
 }
Index: javax/print/FlavorException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/FlavorException.java,v
retrieving revision 1.2
diff -u -r1.2 FlavorException.java
--- javax/print/FlavorException.java    2 Jul 2005 20:32:45 -0000       1.2
+++ javax/print/FlavorException.java    30 Dec 2005 14:51:35 -0000
@@ -1,5 +1,5 @@
 /* FlavorException.java --
-   Copyright (C) 2004 Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,6 +39,16 @@
 package javax.print;
 
 /**
+ * <code>FlavorException</code> specifies a method a specific
+ * subclass of address@hidden javax.print.PrintException} may implement to
+ * provide further information of printing errors if unsupported
+ * document flavors are involved.
+ * <p>
+ * There exists no <code>PrintException</code> class implementing this 
+ * interface. Providing this extension in <code>PrintException</code> 
+ * subclasses is left to the concrete print service implementation.
+ * </p>
+ * 
  * @author Michael Koch (address@hidden)
  */
 public interface FlavorException
@@ -46,7 +56,7 @@
   /**
    * Returns the unsupported document flavors.
    * 
-   * @return the unsupported document flavors
+   * @return The unsupported document flavors.
    */
   DocFlavor[] getUnsupportedFlavors();
 }
\ No newline at end of file
Index: javax/print/URIException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/URIException.java,v
retrieving revision 1.2
diff -u -r1.2 URIException.java
--- javax/print/URIException.java       2 Jul 2005 20:32:46 -0000       1.2
+++ javax/print/URIException.java       30 Dec 2005 14:51:35 -0000
@@ -1,5 +1,5 @@
 /* URIException.java --
-   Copyright (C) 2004 Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,25 +41,48 @@
 import java.net.URI;
 
 /**
+ * <code>URIException</code> specifies methods a specific subclass of 
+ * address@hidden javax.print.PrintException} may implement to provide further 
+ * informations of printing errors if URI problems are involved.
+ * <p>
+ * There exists no <code>PrintException</code> class implementing this 
+ * interface. Providing this extension in <code>PrintException</code> 
+ * subclasses is left to the concrete print service implementation. 
+ * </p>
+ * 
  * @author Michael Koch (address@hidden)
  */
 public interface URIException
 {
+  /**
+   * Indicates that the provided <code>URI</code> is not accessible.
+   */
   int URIInaccessible = 1;
+  
+  /**
+   * Indicates any other problem which is not defined by
+   * the other reason constants.
+   */
   int URIOtherProblem = -1;
+  
+  /**
+   * Indicates that the print service does not support a specific
+   * uri scheme (for example the ftp scheme).
+   */
   int URISchemeNotSupported = 2;
   
   /**
-   * Returns the reason for this exception.
+   * Returns the reason for this exception as
+   * predefined constants in this interface.
    * 
-   * @return the reason
+   * @return The reason.
    */
   int getReason();
   
   /**
-   * Returns the unsupported <code>URI</code> for this exception.
+   * Returns the unsupported <code>URI</code> which caused this exception.
    * 
-   * @return the unsupported <code>URI</code>.
+   * @return The unsupported <code>URI</code>.
    */
   URI getUnsupportedURI();
 }
Index: javax/print/PrintException.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/PrintException.java,v
retrieving revision 1.2
diff -u -r1.2 PrintException.java
--- javax/print/PrintException.java     2 Jul 2005 20:32:46 -0000       1.2
+++ javax/print/PrintException.java     30 Dec 2005 14:51:35 -0000
@@ -1,5 +1,5 @@
 /* PrintException.java --
-   Copyright (C) 2004 Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,6 +39,20 @@
 package javax.print;
 
 /**
+ * <code>PrintException</code> is used to report exceptions during the
+ * usage of a print service implementation.
+ * <p>
+ * This base class only provides the possibility to report a message as 
+ * exception. A concrete print service implementation may provide 
+ * specialised subclasses implementing one or more of the following
+ * exception interfaces:<br>
+ * <ul>
+ * <li>address@hidden javax.print.AttributeException}</li>
+ * <li>address@hidden javax.print.FlavorException}</li>
+ * <li>address@hidden javax.print.URIException}</li>
+ * </ul>
+ * </p>
+ * 
  * @author Michael Koch (address@hidden)
  */
 public class PrintException extends Exception