Hi,
this adds documentation to the interfaces and one exception
in javax.print.attribute.
2005-11-12 Wolfgang Baer <[EMAIL PROTECTED]>
* javax/print/attribute/Attribute.java,
javax/print/attribute/AttributeSet.java,
javax/print/attribute/DocAttribute.java,
javax/print/attribute/DocAttributeSet.java,
javax/print/attribute/PrintJobAttribute.java,
javax/print/attribute/PrintJobAttributeSet.java,
javax/print/attribute/PrintRequestAttribute.java,
javax/print/attribute/PrintRequestAttributeSet.java,
javax/print/attribute/PrintServiceAttribute.java,
javax/print/attribute/PrintServiceAttributeSet.java,
javax/print/attribute/SupportedValuesAttribute.java,
javax/print/attribute/UnmodifiableSetException.java:
Added api documentation to class and method definitions.
* javax/print/attribute/package.html: Included a package description.
OK to commit ?
Regards,
Wolfgang
Index: javax/print/attribute/Attribute.java
===
RCS file: /cvsroot/classpath/classpath/javax/print/attribute/Attribute.java,v
retrieving revision 1.3
diff -u -r1.3 Attribute.java
--- javax/print/attribute/Attribute.java 2 Jul 2005 20:32:46 - 1.3
+++ javax/print/attribute/Attribute.java 12 Nov 2005 19:36:28 -
@@ -1,5 +1,5 @@
/* Attribute.java --
- Copyright (C) 2002 Free Software Foundation, Inc.
+ Copyright (C) 2002, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -40,11 +40,27 @@
import java.io.Serializable;
/**
- * @author Michael Koch
+ * Base interface of every printing attribute of the Java Print Service API.
+ *
+ * @author Michael Koch ([EMAIL PROTECTED])
*/
public interface Attribute extends Serializable
{
+ /**
+ * Returns the category of the printing attribute which is the specific
+ * attribute class implementing this interface.
+ *
+ * @return The concrete [EMAIL PROTECTED] Class} instance of the attribute class.
+ */
Class getCategory ();
+ /**
+ * Returns the descriptive name of the attribute category.
+ *
+ * Implementations of the Attribute interfaces providing equal
+ * category values have to return equal name values.
+ *
+ * @return The name of the attribute category.
+ */
String getName ();
}
Index: javax/print/attribute/AttributeSet.java
===
RCS file: /cvsroot/classpath/classpath/javax/print/attribute/AttributeSet.java,v
retrieving revision 1.3
diff -u -r1.3 AttributeSet.java
--- javax/print/attribute/AttributeSet.java 2 Jul 2005 20:32:46 - 1.3
+++ javax/print/attribute/AttributeSet.java 12 Nov 2005 19:36:28 -
@@ -1,5 +1,5 @@
/* AttributeSet.java --
- Copyright (C) 2002 Free Software Foundation, Inc.
+ Copyright (C) 2002, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -38,40 +38,159 @@
package javax.print.attribute;
/**
- * @author Michael Koch
+ * AttributeSet is the top-level interface for sets of printing
+ * attributes in the Java Print Service API.
+ *
+ * There are no duplicate values allowed in an attribute set and there is
+ * at most one attribute object contained per category type. Based on the
+ * [EMAIL PROTECTED] java.util.Map} interface the values of attribute sets are objects
+ * of type [EMAIL PROTECTED] javax.print.attribute.Attribute} and the entries are the
+ * categories as [EMAIL PROTECTED] java.lang.Class} instances.
+ *
+ *
+ * The following specialized types of AttributeSet are available:
+ *
+ * [EMAIL PROTECTED] javax.print.attribute.DocAttributeSet}
+ * [EMAIL PROTECTED] javax.print.attribute.PrintRequestAttributeSet}
+ * [EMAIL PROTECTED] javax.print.attribute.PrintJobAttributeSet}
+ * [EMAIL PROTECTED] javax.print.attribute.PrintServiceAttributeSet}
+ *
+ *
+ *
+ * Attribute sets may be unmodifiable depending on the context of usage. If
+ * used as read-only attribute set modifying operations throw an
+ * [EMAIL PROTECTED] javax.print.attribute.UnmodifiableSetException}.
+ *
+ *
+ * The Java Print Service API provides implementation classes for the existing
+ * attribute set interfaces but applications may use their own implementations.
+ *
+ *
+ * @author Michael Koch ([EMAIL PROTECTED])
*/
public interface AttributeSet
{
/**
- * Adds the specified attribute value to this attribute set
+ * Adds the specified attribute value to this attribute set
* if it is not already present.
+ *
+ * This operation removes any existing attribute of the same category
+ * before adding the given attribute to the set.
+ *
+ * @param attribute the attribute to add.
+ * @return true if the set is changed, false otherwise.
+ * @throws NullPointerException if the attribute is null.
+ * @throws UnmodifiableSetException if the set does not support modification.
*/
boolean add (Attrib
