Hi,
this adds the missing class documentations for javax.print.
The Java Print Service API should now be completely documented. Although,
the documentation of the printing attributes could be quite enhanced
if there will be a positive decision about the usage of RFC documents
at sometime.
2006-03-12 Wolfgang Baer <[EMAIL PROTECTED]>
* javax/print/MultiDocPrintService.java,
* javax/print/MultiDocPrintJob.java,
* javax/print/MultiDoc.java: Added and enhanced documentation.
Regards,
Wolfgang
Index: javax/print/MultiDoc.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/MultiDoc.java,v
retrieving revision 1.2
diff -u -r1.2 MultiDoc.java
--- javax/print/MultiDoc.java 2 Jul 2005 20:32:45 -0000 1.2
+++ javax/print/MultiDoc.java 12 Mar 2006 19:00:05 -0000
@@ -1,5 +1,5 @@
/* MultiDoc.java --
- Copyright (C) 2004 Free Software Foundation, Inc.
+ Copyright (C) 2004, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -42,6 +42,25 @@
/**
+ * <code>MultiDoc</code> defines the interface for objects providing multiple
+ * documents for use in a print job.
+ * <p>
+ * Implementations of this interface are used to pass multiple documents, to be
+ * printed as one print job, to the <code>MultiDocPrintJob</code> instance.
+ * </p><p>
+ * There exists no implementation of this interface in the Java Print Service
+ * API. Implementors may assume the following usage in print jobs and the needed
+ * behaviour for implementations: The print job fetches the single documents via
+ * iteration by consecutive calls of the [EMAIL PROTECTED] #getDoc()} method to obtain the
+ * current document follwing calls of the [EMAIL PROTECTED] #next()} method to get the next
+ * multidoc object for the next <code>getDoc()</code> method call (if returned
+ * multidoc object is not <code>null</code>). The print service will fetch the
+ * document object and then retrieve the print data from the document before it
+ * proceeds with the next call for the next MultiDoc object in the sequence.
+ * </p><p>
+ * Implementations of this interface have to be multiple thread-safe.
+ * </p>
+ *
* @author Michael Koch ([EMAIL PROTECTED])
*/
public interface MultiDoc
@@ -49,16 +68,18 @@
/**
* Returns the current document.
*
- * @return the current document
+ * @return The current document.
*
* @throws IOException if an error occurs
*/
Doc getDoc() throws IOException;
/**
- * Returns the next <code>MultiDoc</code> object.
+ * Returns the next <code>MultiDoc</code> object that contains the
+ * next document for retrieval.
*
- * @return the next <code>MultiDoc</code> object
+ * @return The next <code>MultiDoc</code> object, or <code>null</code>
+ * if no more documents are available.
*
* @throws IOException if an error occurs
*/
Index: javax/print/MultiDocPrintJob.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/MultiDocPrintJob.java,v
retrieving revision 1.2
diff -u -r1.2 MultiDocPrintJob.java
--- javax/print/MultiDocPrintJob.java 2 Jul 2005 20:32:45 -0000 1.2
+++ javax/print/MultiDocPrintJob.java 12 Mar 2006 19:00:05 -0000
@@ -1,5 +1,5 @@
/* MultiDocPrintJob.java --
- Copyright (C) 2004 Free Software Foundation, Inc.
+ Copyright (C) 2004, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -42,17 +42,34 @@
/**
+ * <code>MultiDocPrintJob</code> represents a print job which supports
+ * printing of multiple documents as one print job.
+ * <p>
+ * An instance can be obtained from every <code>MultiDocPrintService</code>
+ * available by calling the
+ * [EMAIL PROTECTED] javax.print.MultiDocPrintService#createMultiDocPrintJob()} method.
+ * A print job is bound to the print service it is created from.
+ * </p>
+ *
* @author Michael Koch ([EMAIL PROTECTED])
*/
public interface MultiDocPrintJob extends DocPrintJob
{
/**
- * Request a print of a <code>MultiDoc</code> object.
+ * Prints the documents supplied in the given <code>MultiDoc</code> object
+ * as one print job with the given printing attributes.
*
- * @param multiDoc the document to print
- * @param attributes the printing attributes to apply
+ * @param multiDoc the documents to print. Every document must have a
+ * flavor supported by the bound print service.
+ * @param attributes the printing attributes to apply to the print job. If
+ * <code>null</code> the default attribute values will be used.
*
- * @throws PrintExeption if an error occurs
+ * @throws PrintException if an error occurs. The thrown exception may
+ * implement refining print exception interface to provide more detail of
+ * the error.
+ *
+ * @see FlavorException
+ * @see AttributeException
*/
void print(MultiDoc multiDoc, PrintRequestAttributeSet attributes)
throws PrintException;
Index: javax/print/MultiDocPrintService.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/print/MultiDocPrintService.java,v
retrieving revision 1.2
diff -u -r1.2 MultiDocPrintService.java
--- javax/print/MultiDocPrintService.java 2 Jul 2005 20:32:46 -0000 1.2
+++ javax/print/MultiDocPrintService.java 12 Mar 2006 19:00:05 -0000
@@ -1,5 +1,5 @@
/* MultiDocPrintService.java --
- Copyright (C) 2004 Free Software Foundation, Inc.
+ Copyright (C) 2004, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -40,6 +40,13 @@
/**
+ * <code>MultiDocPrintService</code> represents print services that are
+ * capable of printing multiple documents as one print job. It provides an
+ * additional method for the creation of a print job for multiple documents.
+ *
+ * @see javax.print.MultiDoc
+ * @see javax.print.MultiDocPrintJob
+ *
* @author Michael Koch ([EMAIL PROTECTED])
*/
public interface MultiDocPrintService extends PrintService
@@ -47,7 +54,7 @@
/**
* Create a job that can print a <code>MultiDoc</code> object.
*
- * @return the new print job
+ * @return The created print job.
*/
MultiDocPrintJob createMultiDocPrintJob();
}
\ No newline at end of file
