2006-03-12 Wolfgang Baer <WBaer@gmx.de>

	* javax/print/MultiDocPrintService.java,
	* javax/print/MultiDocPrintJob.java,
	* javax/print/MultiDoc.java: Added and enhanced documentation.

3 files changed, 56 insertions, 11 deletions

diff --git a/javax/print/MultiDoc.java b/javax/print/MultiDoc.java
index e7747bca7..6e9ec841f 100644
--- a/javax/print/MultiDoc.java
+++ b/javax/print/MultiDoc.java
@@ -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 @@ import java.io.IOException;
 
 
 /**
+ * <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 {@link #getDoc()} method to obtain the 
+ * current document follwing calls of the {@link #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 (konqueror@gmx.de)
  */
 public interface MultiDoc
@@ -49,16 +68,18 @@ public interface MultiDoc
   /**
    * 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
    */
diff --git a/javax/print/MultiDocPrintJob.java b/javax/print/MultiDocPrintJob.java
index b096769b0..36089b5d0 100644
--- a/javax/print/MultiDocPrintJob.java
+++ b/javax/print/MultiDocPrintJob.java
@@ -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 @@ import javax.print.attribute.PrintRequestAttributeSet;
 
 
 /**
+ * <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 
+ * {@link javax.print.MultiDocPrintService#createMultiDocPrintJob()} method. 
+ * A print job is bound to the print service it is created from.
+ * </p>
+ * 
  * @author Michael Koch (konqueror@gmx.de)
  */
 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;
diff --git a/javax/print/MultiDocPrintService.java b/javax/print/MultiDocPrintService.java
index a71d23a28..105e72210 100644
--- a/javax/print/MultiDocPrintService.java
+++ b/javax/print/MultiDocPrintService.java
@@ -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 @@ package javax.print;
 
 
 /**
+ * <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 (konqueror@gmx.de)
  */
 public interface MultiDocPrintService extends PrintService
@@ -47,7 +54,7 @@ public interface MultiDocPrintService extends PrintService
   /**
    * 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