[cp-patches] Patch: javax.print.event.* API docs

[Wolfgang Baer]

Hi all,

this patch adds api docs to the javax.print.event package.

2005-11-03  Wolfgang Baer  <address@hidden>

        * javax/print/event/*: Added API docs all over.

Regards,

Wolfgang

Index: javax/print/event/PrintEvent.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/event/PrintEvent.java,v
retrieving revision 1.2
diff -u -r1.2 PrintEvent.java
--- javax/print/event/PrintEvent.java   2 Jul 2005 20:32:46 -0000       1.2
+++ javax/print/event/PrintEvent.java   3 Nov 2005 19:27:30 -0000
@@ -1,5 +1,5 @@
 /* PrintEvent.java -- 
-   Copyright (C) 2004  Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,6 +41,8 @@
 
 
 /**
+ * Superclass of all events in the Java Print Service API.
+ * 
  * @author Michael Koch (address@hidden)
  */
 public class PrintEvent extends EventObject
@@ -58,7 +60,7 @@
   /**
    * Returns a string representation of this object.
    * 
-   * @return the string representation
+   * @return The string representation
    */
   public String toString()
   {
Index: javax/print/event/PrintJobAdapter.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/event/PrintJobAdapter.java,v
retrieving revision 1.2
diff -u -r1.2 PrintJobAdapter.java
--- javax/print/event/PrintJobAdapter.java      2 Jul 2005 20:32:46 -0000       
1.2
+++ javax/print/event/PrintJobAdapter.java      3 Nov 2005 19:27:30 -0000
@@ -1,5 +1,5 @@
 /* PrintJobAdapter.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,11 @@
 
 
 /**
+ * Adapter class for implementing address@hidden 
javax.print.event.PrintJobListener}
+ * classes. The methods in this class do nothing by default. Subclasses may
+ * only implement the methods for the address@hidden 
javax.print.event.PrintJobEvent}s
+ * they are interested in.
+ * 
  * @author Michael Koch (address@hidden)
  */
 public abstract class PrintJobAdapter
@@ -53,10 +58,11 @@
   }
   
   /**
-   * Called to notify the client that all data has bin successfully transferred
+   * Called to notify the client that all data has been successfully 
transferred
    * to the print service.
+   * <p>The default implementation does nothing.</p>
    * 
-   * <p>The default implementation does nothing</p>
+   * @param event the event. 
    */
   public void printDataTransferCompleted(PrintJobEvent event)
   {
@@ -64,9 +70,10 @@
   }
 
   /**
-   * Called to notify the client that a print job was canceled.
+   * Called to notify the client that a print job was canceled. 
+   * <p>The default implementation does nothing.</p>
    * 
-   * <p>The default implementation does nothing</p>
+   * @param event the event. 
    */
   public void printJobCanceled(PrintJobEvent event)
   {
@@ -75,8 +82,9 @@
 
   /**
    * Called to notify the client that a print job was successfully completed.
+   * <p>The default implementation does nothing.</p>
    * 
-   * <p>The default implementation does nothing</p>
+   * @param event the event. 
    */
   public void printJobCompleted(PrintJobEvent event)
   {
@@ -86,8 +94,9 @@
   /**
    * Called to notify the client that a print job failed to complete
    * successfully.
+   * <p>The default implementation does nothing.</p>
    * 
-   * <p>The default implementation does nothing</p>
+   * @param event the event. 
    */
   public void printJobFailed(PrintJobEvent event)
   {
@@ -96,8 +105,9 @@
 
   /**
    * Called to notify the client that no more job events will be send.
+   * <p>The default implementation does nothing.</p>
    * 
-   * <p>The default implementation does nothing</p>
+   * @param event the event. 
    */
   public void printJobNoMoreEvents(PrintJobEvent event)
   {
@@ -105,10 +115,12 @@
   }
 
   /**
-   * Called to notify the client that a problem occured during printing
-   * but the user may be able to fix it.
+   * Called to notify the client that a problem occured during printing.
+   * This event signals problems a user might be able to fix 
+   * (e.g. out of paper or paper jam).
+   * <p>The default implementation does nothing.</p>
    * 
-   * <p>The default implementation does nothing</p>
+   * @param event the event. 
    */
   public void printJobRequiresAttention(PrintJobEvent event)
   {
Index: javax/print/event/PrintJobAttributeEvent.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/print/event/PrintJobAttributeEvent.java,v
retrieving revision 1.2
diff -u -r1.2 PrintJobAttributeEvent.java
--- javax/print/event/PrintJobAttributeEvent.java       2 Jul 2005 20:32:46 
-0000       1.2
+++ javax/print/event/PrintJobAttributeEvent.java       3 Nov 2005 19:27:30 
-0000
@@ -1,5 +1,5 @@
 /* PrintJobAttributeEvent.java -- 
-   Copyright (C) 2004  Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -42,6 +42,10 @@
 
 
 /**
+ * <code>PrintJobAttributeEvent</code>s are generated by a 
+ * <code>PrintService</code> to inform registered listeners that attributes
+ * associated with a address@hidden javax.print.DocPrintJob} instance have 
changed.
+ * 
  * @author Michael Koch (address@hidden)
  */
 public class PrintJobAttributeEvent extends PrintEvent
@@ -66,7 +70,7 @@
   /**
    * Returns the print job generating this event.
    * 
-   * @return the print job
+   * @return The print job.
    */
   public DocPrintJob getPrintJob()
   {
@@ -76,7 +80,7 @@
   /**
    * Returns the attributes that changed and their new values.
    * 
-   * @return the changes attributes
+   * @return The changed attributes.
    */
   public PrintJobAttributeSet getAttributes()
   {
Index: javax/print/event/PrintJobAttributeListener.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/print/event/PrintJobAttributeListener.java,v
retrieving revision 1.2
diff -u -r1.2 PrintJobAttributeListener.java
--- javax/print/event/PrintJobAttributeListener.java    2 Jul 2005 20:32:46 
-0000       1.2
+++ javax/print/event/PrintJobAttributeListener.java    3 Nov 2005 19:27:30 
-0000
@@ -1,5 +1,5 @@
 /* PrintJobAttributeListener.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,10 @@
 
 
 /**
+ * Listener interface to receive attribute changes from a print job.
+ * Implementations of this interface can be registered with a 
+ * address@hidden javax.print.DocPrintJob} instance.
+ *  
  * @author Michael Koch (address@hidden)
  */
 public interface PrintJobAttributeListener
Index: javax/print/event/PrintJobEvent.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/event/PrintJobEvent.java,v
retrieving revision 1.2
diff -u -r1.2 PrintJobEvent.java
--- javax/print/event/PrintJobEvent.java        2 Jul 2005 20:32:46 -0000       
1.2
+++ javax/print/event/PrintJobEvent.java        3 Nov 2005 19:27:30 -0000
@@ -1,5 +1,5 @@
 /* PrintEvent.java -- 
-   Copyright (C) 2004  Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,19 +41,38 @@
 
 
 /**
+ * <code>PrintJobEvent</code>s are generated by a print job during
+ * print job processing to inform registered listeners about the state
+ * of processing.
+ * 
  * @author Michael Koch (address@hidden)
  */
 public class PrintJobEvent extends PrintEvent
 {
   private static final long serialVersionUID = -1711656903622072997L;
-
+  
+  /** Indicates that the data transfer to the print service has completed. */
   public static final int DATA_TRANSFER_COMPLETE = 106;
+  
+  /** Indicates that the print job was canceled. */
   public static final int JOB_CANCELED = 101;
+  
+  /** Indicates that the print job was completed (=printed). */
   public static final int JOB_COMPLETE = 102;
+  
+  /** Indicates that the print job failed to complete. */
   public static final int JOB_FAILED = 103;
+  
+  /** Indicates that no more job events will be send.*/
   public static final int NO_MORE_EVENTS = 105;
+  
+  /** 
+   * Indicates a situation where human intervention might be needed.
+   * E.g. the printer run out of paper or a paper jam occured.
+   */
   public static final int REQUIRES_ATTENTION = 104;
   
+  /** The reason (one of the defined constants). */
   private int reason;
   
   /**
@@ -71,7 +90,7 @@
   /**
    * Returns the reason for this event.
    * 
-   * @return the reason
+   * @return The reason.
    */
   public int getPrintEventType()
   {
@@ -81,7 +100,7 @@
   /**
    * Returns the print job that generated this event.
    * 
-   * @return the print job
+   * @return The print job.
    */ 
   public DocPrintJob getPrintJob()
   {
Index: javax/print/event/PrintJobListener.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/event/PrintJobListener.java,v
retrieving revision 1.2
diff -u -r1.2 PrintJobListener.java
--- javax/print/event/PrintJobListener.java     2 Jul 2005 20:32:46 -0000       
1.2
+++ javax/print/event/PrintJobListener.java     3 Nov 2005 19:27:30 -0000
@@ -1,5 +1,5 @@
 /* PrintJobListener.java -- 
-   Copyright (C) 2004  Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,7 +39,14 @@
 
 
 /**
- * @author Michael Koch (address@hidden) */
+ * Listener interface to receive processing events from a print job.
+ * Implementations of this interface can be registered with a 
+ * address@hidden javax.print.DocPrintJob} instance.
+ * 
+ * @see javax.print.event.PrintJobAdapter
+ *  
+ * @author Michael Koch (address@hidden) 
+ */
 public interface PrintJobListener
 {
   /**
@@ -79,7 +86,9 @@
   void printJobNoMoreEvents(PrintJobEvent event);
   
   /**
-   * Notifies the listener that an error occured and the user might be able to 
fix it.
+   * Notifies the listener that a problem occured during printing.
+   * This event signals problems a user might be able to fix 
+   * (e.g. out of paper or paper jam).
    * 
    * @param event the event
    */
Index: javax/print/event/PrintServiceAttributeEvent.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/print/event/PrintServiceAttributeEvent.java,v
retrieving revision 1.2
diff -u -r1.2 PrintServiceAttributeEvent.java
--- javax/print/event/PrintServiceAttributeEvent.java   2 Jul 2005 20:32:46 
-0000       1.2
+++ javax/print/event/PrintServiceAttributeEvent.java   3 Nov 2005 19:27:30 
-0000
@@ -1,5 +1,5 @@
 /* PrintServiceAttributeEvent.java -- 
-   Copyright (C) 2004  Free Software Foundation, Inc.
+   Copyright (C) 2004, 2005  Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -42,6 +42,10 @@
 
 
 /**
+ * <code>PrintServiceAttributeEvent</code>s are generated by a 
+ * <code>PrintService</code> to inform registered listeners that
+ * its associated attributes have changed.
+ * 
  * @author Michael Koch (address@hidden)
  */
 public class PrintServiceAttributeEvent extends PrintEvent
@@ -64,7 +68,7 @@
   /**
    * Returns the print service that generated this event.
    * 
-   * @return the print service
+   * @return The print service.
    */
   public PrintService getPrintService()
   {
@@ -74,7 +78,7 @@
   /**
    * Returns the changed attributes this event reports.
    * 
-   * @return the changed attributes
+   * @return The changed attributes.
    */
   public PrintServiceAttributeSet getAttributes()
   {
Index: javax/print/event/PrintServiceAttributeListener.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/print/event/PrintServiceAttributeListener.java,v
retrieving revision 1.2
diff -u -r1.2 PrintServiceAttributeListener.java
--- javax/print/event/PrintServiceAttributeListener.java        2 Jul 2005 
20:32:46 -0000       1.2
+++ javax/print/event/PrintServiceAttributeListener.java        3 Nov 2005 
19:27:30 -0000
@@ -1,5 +1,5 @@
 /* PrintServiceAttributeListener.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,10 @@
 
 
 /**
+ * Listener interface to receive attribute changes from a print service.
+ * Implementations of this interface can be registered with a 
+ * address@hidden javax.print.PrintService} instance.
+ * 
  * @author Michael Koch (address@hidden)
  */
 public interface PrintServiceAttributeListener
Index: javax/print/event/package.html
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/event/package.html,v
retrieving revision 1.2
diff -u -r1.2 package.html
--- javax/print/event/package.html      2 Jul 2005 20:32:46 -0000       1.2
+++ javax/print/event/package.html      3 Nov 2005 19:27:30 -0000
@@ -1,6 +1,6 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <!-- package.html - describes classes in javax.print.event package.
-   Copyright (C) 2003 Free Software Foundation, Inc.
+   Copyright (C) 2003, 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,7 +40,9 @@
 <head><title>GNU Classpath - javax.print.event</title></head>
 
 <body>
-<p></p>
-
+<p>Provides events and listeners to be used with the Java Print Service 
API.</p>
+<p>
+<b>Since:</b> 1.4
+</p>
 </body>
 </html>