String.java, [...]: Merge from GNU Classpath HEAD.

2006-06-09  Thomas Fitzsimmons  <fitzsim@redhat.com>

	* java/lang/String.java, classpath/native/jni/classpath/jcl.h,
	classpath/native/jni/qt-peer/eventmethods.h,
	classpath/native/jni/qt-peer/qtmenupeer.cpp,
	classpath/native/jni/qt-peer/.cvsignore,
	classpath/native/jni/gtk-peer/gdkdisplay.h,
	classpath/native/jni/gtk-peer/cairographics2d.h,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_CairoGraphics2D.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GdkFontPeer.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_FreetypeGlyphVector.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GdkGraphicsEnvironment.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_ComponentGraphicsCopy.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_ComponentGraphics.c,
	classpath/native/jni/gtk-peer/.cvsignore,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GtkImage.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GtkVolatileImage.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GtkToolkit.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GtkCanvasPeer.c,
	classpath/native/jni/gtk-peer/gtkpeer.h,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GtkClipboard.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_CairoSurface.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GdkScreenGraphicsDevice.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GdkTextLayout.c,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GtkFramePeer.c,
	classpath/native/jni/gtk-peer/Makefile.am,
	classpath/native/jni/gtk-peer/gnu_java_awt_peer_gtk_GtkComponentPeer.c,
	classpath/native/jawt/Makefile.am,
	classpath/native/jawt/.cvsignore,
	classpath/native/target/Linux/Makefile.in,
	classpath/native/plugin/gcjwebplugin.cc,
	classpath/native/plugin/Makefile.am,
	classpath/native/plugin/.cvsignore,
	classpath/resource/Makefile.in,
	classpath/gnu/java/awt/peer/gtk/VolatileImageGraphics.java,
	classpath/gnu/java/awt/peer/gtk/CairoGraphics2D.java,
	classpath/gnu/java/awt/peer/gtk/CairoSurface.java,
	classpath/gnu/java/awt/peer/gtk/GdkFontPeer.java,
	classpath/gnu/java/awt/peer/gtk/GdkPixbufDecoder.java,
	classpath/gnu/java/awt/peer/gtk/FreetypeGlyphVector.java,
	classpath/gnu/java/awt/peer/gtk/GdkGraphicsEnvironment.java,
	classpath/gnu/java/awt/peer/gtk/GdkGraphics2D.java,
	classpath/gnu/java/awt/peer/gtk/ComponentGraphicsCopy.java,
	classpath/gnu/java/awt/peer/gtk/GtkComponentPeer.java,
	classpath/gnu/java/awt/peer/gtk/GdkGraphics.java,
	classpath/gnu/java/awt/peer/gtk/GtkToolkit.java,
	classpath/gnu/java/awt/peer/gtk/GdkScreenGraphicsDevice.java,
	classpath/gnu/java/awt/peer/gtk/BufferedImageGraphics.java,
	classpath/gnu/java/awt/peer/gtk/GdkTextLayout.java,
	classpath/gnu/java/awt/peer/gtk/GdkGraphicsConfiguration.java,
	classpath/gnu/java/awt/peer/gtk/ComponentGraphics.java,
	classpath/gnu/java/awt/peer/gtk/CairoSurfaceGraphics.java,
	classpath/gnu/java/awt/peer/gtk/GtkImage.java,
	classpath/gnu/java/awt/peer/gtk/GtkVolatileImage.java,
	classpath/gnu/java/awt/peer/gtk/GdkGlyphVector.java,
	classpath/gnu/java/awt/peer/gtk/GtkCanvasPeer.java,
	classpath/gnu/java/awt/peer/swing/SwingContainerPeer.java,
	classpath/gnu/java/awt/peer/swing/SwingComponent.java,
	classpath/gnu/java/awt/peer/swing/SwingTextFieldPeer.java,
	classpath/gnu/java/awt/peer/swing/SwingMenuBarPeer.java,
	classpath/gnu/java/awt/peer/swing/SwingFramePeer.java,
	classpath/gnu/java/awt/peer/swing/SwingComponentPeer.java,
	classpath/gnu/java/awt/peer/swing/SwingWindowPeer.java,
	classpath/gnu/java/awt/print/JavaPrinterJob.java,
	classpath/gnu/java/awt/print/PostScriptGraphics2D.java,
	classpath/gnu/java/awt/print/SpooledDocument.java,
	classpath/gnu/java/awt/print/JavaPrinterGraphics.java,
	classpath/gnu/java/awt/BitwiseXORComposite.java,
	classpath/gnu/java/awt/font/GNUGlyphVector.java,
	classpath/gnu/java/awt/font/opentype/NameDecoder.java,
	classpath/gnu/java/awt/java2d/RasterGraphics.java,
	classpath/gnu/java/awt/java2d/TexturePaintContext.java,
	classpath/gnu/java/awt/java2d/PolyEdge.java,
	classpath/gnu/java/awt/java2d/AbstractGraphics2D.java,
	classpath/gnu/java/awt/java2d/AlphaCompositeContext.java,
	classpath/gnu/java/awt/java2d/ImagePaint.java,
	classpath/gnu/java/awt/Buffers.java,
	classpath/gnu/classpath/Configuration.java.in,
	classpath/gnu/javax/swing/text/html/CombinedAttributes.java,
	classpath/gnu/javax/swing/text/html/CharacterAttributeTranslator.java,
	classpath/gnu/javax/swing/text/html/parser/htmlAttributeSet.java,
	classpath/gnu/javax/swing/text/html/parser/SmallHtmlAttributeSet.java,
	classpath/gnu/javax/swing/text/html/ImageViewIconFactory.java,
	classpath/tools/toolwrapper.c,
	classpath/tools/gnu/classpath/tools/native2ascii/Native2ASCII.java,
	classpath/tools/gnu/classpath/tools/native2ascii/Messages.java,
	classpath/tools/gnu/classpath/tools/getopt/FileArgumentCallback.java,
	classpath/tools/gnu/classpath/tools/getopt/OptionGroup.java,
	classpath/tools/gnu/classpath/tools/getopt/OptionException.java,
	classpath/tools/gnu/classpath/tools/getopt/Messages.java,
	classpath/tools/gnu/classpath/tools/getopt/Option.java,
	classpath/tools/gnu/classpath/tools/getopt/Parser.java,
	classpath/tools/gnu/classpath/tools/getopt/ClasspathToolParser.java,
	classpath/tools/gnu/classpath/tools/jarsigner/JarSigner.java,
	classpath/tools/gnu/classpath/tools/jarsigner/Main.java,
	classpath/tools/gnu/classpath/tools/jarsigner/Messages.java,
	classpath/tools/gnu/classpath/tools/jarsigner/package.html,
	classpath/tools/gnu/classpath/tools/keytool/ListCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/StorePasswdCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/ExportCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/GenKeyCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/Messages.java,
	classpath/tools/gnu/classpath/tools/keytool/package.html,
	classpath/tools/gnu/classpath/tools/keytool/Command.java,
	classpath/tools/gnu/classpath/tools/keytool/IdentityDBCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/Main.java,
	classpath/tools/gnu/classpath/tools/keytool/DeleteCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/CertReqCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/SelfCertCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/KeyCloneCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/KeyPasswdCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/ImportCmd.java,
	classpath/tools/gnu/classpath/tools/keytool/PrintCertCmd.java,
	classpath/tools/gnu/classpath/tools/rmi/registry/package.html,
	classpath/tools/gnu/classpath/tools/rmi/RMIC.txt,
	classpath/tools/gnu/classpath/tools/rmi/RMIC.java,
	classpath/tools/gnu/classpath/tools/appletviewer/ErrorApplet.java,
	classpath/tools/gnu/classpath/tools/appletviewer/AppletClassLoader.java,
	classpath/tools/gnu/classpath/tools/appletviewer/CommonAppletContext.java,
	classpath/tools/gnu/classpath/tools/appletviewer/StandaloneAppletContext.java,
	classpath/tools/gnu/classpath/tools/appletviewer/AppletSecurityManager.java,
	classpath/tools/gnu/classpath/tools/appletviewer/PluginAppletContext.java,
	classpath/tools/gnu/classpath/tools/appletviewer/AppletWarning.java,
	classpath/tools/gnu/classpath/tools/appletviewer/StandaloneAppletViewer.java,
	classpath/tools/gnu/classpath/tools/appletviewer/AppletTag.java,
	classpath/tools/gnu/classpath/tools/appletviewer/ConsoleDialog.java,
	classpath/tools/gnu/classpath/tools/appletviewer/Main.java,
	classpath/tools/gnu/classpath/tools/appletviewer/StandaloneAppletWindow.java,
	classpath/tools/gnu/classpath/tools/appletviewer/PluginAppletViewer.java,
	classpath/tools/gnu/classpath/tools/appletviewer/TagParser.java,
	classpath/tools/gnu/classpath/tools/appletviewer/PluginAppletWindow.java,
	classpath/tools/gnu/classpath/tools/appletviewer/CommonAppletStub.java,
	classpath/tools/gnu/classpath/tools/serialver/Messages.java,
	classpath/tools/gnu/classpath/tools/serialver/SerialVer.java,
	classpath/tools/gnu/classpath/tools/jar/Creator.java,
	classpath/tools/gnu/classpath/tools/jar/Entry.java,
	classpath/tools/gnu/classpath/tools/jar/Lister.java,
	classpath/tools/gnu/classpath/tools/jar/Main.java,
	classpath/tools/gnu/classpath/tools/jar/Updater.java,
	classpath/tools/gnu/classpath/tools/jar/Messages.java,
	classpath/tools/gnu/classpath/tools/jar/Extractor.java,
	classpath/tools/gnu/classpath/tools/jar/Action.java,
	classpath/tools/gnu/classpath/tools/jar/Indexer.java,
	classpath/tools/gnu/classpath/tools/jar/WorkSet.java,
	classpath/tools/gnu/classpath/tools/giop/GRMIC.txt,
	classpath/tools/gnu/classpath/tools/giop/grmic/GiopRmicCompiler.java,
	classpath/tools/gnu/classpath/tools/giop/GRMIC.java,
	classpath/tools/Makefile.am, classpath/tools/jarsigner.in,
	classpath/tools/keytool.in, classpath/tools/appletviewer.in,
	classpath/tools/.cvsignore, classpath/configure.ac,
	classpath/javax/swing/JTabbedPane.java,
	classpath/javax/swing/AbstractButton.java,
	classpath/javax/swing/JViewport.java,
	classpath/javax/swing/KeyboardManager.java,
	classpath/javax/swing/JMenuItem.java,
	classpath/javax/swing/JMenuBar.java,
	classpath/javax/swing/MenuSelectionManager.java,
	classpath/javax/swing/JOptionPane.java,
	classpath/javax/swing/JSpinner.java,
	classpath/javax/swing/JCheckBoxMenuItem.java,
	classpath/javax/swing/JEditorPane.java,
	classpath/javax/swing/JFormattedTextField.java,
	classpath/javax/swing/JTree.java,
	classpath/javax/swing/CellRendererPane.java,
	classpath/javax/swing/JScrollPane.java,
	classpath/javax/swing/tree/VariableHeightLayoutCache.java,
	classpath/javax/swing/tree/TreeNode.java,
	classpath/javax/swing/tree/FixedHeightLayoutCache.java,
	classpath/javax/swing/tree/DefaultTreeCellEditor.java,
	classpath/javax/swing/tree/TreePath.java,
	classpath/javax/swing/tree/RowMapper.java,
	classpath/javax/swing/tree/DefaultMutableTreeNode.java,
	classpath/javax/swing/tree/DefaultTreeModel.java,
	classpath/javax/swing/tree/AbstractLayoutCache.java,
	classpath/javax/swing/tree/TreeSelectionModel.java,
	classpath/javax/swing/tree/DefaultTreeSelectionModel.java,
	classpath/javax/swing/tree/DefaultTreeCellRenderer.java,
	classpath/javax/swing/tree/ExpandVetoException.java,
	classpath/javax/swing/JList.java,
	classpath/javax/swing/table/JTableHeader.java,
	classpath/javax/swing/table/AbstractTableModel.java,
	classpath/javax/swing/table/DefaultTableModel.java,
	classpath/javax/swing/table/TableCellEditor.java,
	classpath/javax/swing/table/TableCellRenderer.java,
	classpath/javax/swing/ProgressMonitor.java,
	classpath/javax/swing/JToolBar.java,
	classpath/javax/swing/TransferHandler.java,
	classpath/javax/swing/DefaultCellEditor.java,
	classpath/javax/swing/DefaultButtonModel.java,
	classpath/javax/swing/JLayeredPane.java,
	classpath/javax/swing/text/DefaultEditorKit.java,
	classpath/javax/swing/text/DefaultCaret.java,
	classpath/javax/swing/text/FieldView.java,
	classpath/javax/swing/text/JTextComponent.java,
	classpath/javax/swing/text/TextAction.java,
	classpath/javax/swing/text/StyleContext.java,
	classpath/javax/swing/text/html/HTMLDocument.java,
	classpath/javax/swing/text/html/MinimalHTMLWriter.java,
	classpath/javax/swing/text/html/ImageView.java,
	classpath/javax/swing/text/html/HTMLEditorKit.java,
	classpath/javax/swing/text/AbstractWriter.java,
	classpath/javax/swing/text/GapContent.java,
	classpath/javax/swing/text/Utilities.java,
	classpath/javax/swing/text/PlainView.java,
	classpath/javax/swing/UIManager.java,
	classpath/javax/swing/JSplitPane.java,
	classpath/javax/swing/JComponent.java,
	classpath/javax/swing/SwingUtilities.java,
	classpath/javax/swing/border/AbstractBorder.java,
	classpath/javax/swing/border/CompoundBorder.java,
	classpath/javax/swing/border/TitledBorder.java,
	classpath/javax/swing/border/MatteBorder.java,
	classpath/javax/swing/border/BevelBorder.java,
	classpath/javax/swing/RepaintManager.java,
	classpath/javax/swing/JTable.java,
	classpath/javax/swing/UIDefaults.java,
	classpath/javax/swing/DefaultDesktopManager.java,
	classpath/javax/swing/JMenu.java,
	classpath/javax/swing/JLabel.java,
	classpath/javax/swing/JSlider.java,
	classpath/javax/swing/plaf/basic/BasicToolBarUI.java,
	classpath/javax/swing/plaf/basic/BasicButtonUI.java,
	classpath/javax/swing/plaf/basic/BasicOptionPaneUI.java,
	classpath/javax/swing/plaf/basic/BasicTextAreaUI.java,
	classpath/javax/swing/plaf/basic/BasicToggleButtonUI.java,
	classpath/javax/swing/plaf/basic/BasicSpinnerUI.java,
	classpath/javax/swing/plaf/basic/BasicSliderUI.java,
	classpath/javax/swing/plaf/basic/BasicTabbedPaneUI.java,
	classpath/javax/swing/plaf/basic/BasicComboPopup.java,
	classpath/javax/swing/plaf/basic/BasicCheckBoxUI.java,
	classpath/javax/swing/plaf/basic/BasicInternalFrameUI.java,
	classpath/javax/swing/plaf/basic/BasicProgressBarUI.java,
	classpath/javax/swing/plaf/basic/BasicRadioButtonUI.java,
	classpath/javax/swing/plaf/basic/BasicPanelUI.java,
	classpath/javax/swing/plaf/basic/BasicSplitPaneUI.java,
	classpath/javax/swing/plaf/basic/BasicTreeUI.java,
	classpath/javax/swing/plaf/basic/BasicTableHeaderUI.java,
	classpath/javax/swing/plaf/basic/BasicFileChooserUI.java,
	classpath/javax/swing/plaf/basic/BasicScrollPaneUI.java,
	classpath/javax/swing/plaf/basic/BasicComboBoxUI.java,
	classpath/javax/swing/plaf/basic/BasicListUI.java,
	classpath/javax/swing/plaf/basic/BasicIconFactory.java,
	classpath/javax/swing/plaf/basic/BasicTextUI.java,
	classpath/javax/swing/plaf/basic/BasicLookAndFeel.java,
	classpath/javax/swing/plaf/basic/BasicDirectoryModel.java,
	classpath/javax/swing/plaf/basic/BasicRootPaneUI.java,
	classpath/javax/swing/plaf/basic/BasicTableUI.java,
	classpath/javax/swing/plaf/basic/SharedUIDefaults.java,
	classpath/javax/swing/plaf/multi/MultiComboBoxUI.java,
	classpath/javax/swing/plaf/multi/MultiListUI.java,
	classpath/javax/swing/plaf/multi/MultiSplitPaneUI.java,
	classpath/javax/swing/plaf/multi/MultiFileChooserUI.java,
	classpath/javax/swing/plaf/multi/MultiOptionPaneUI.java,
	classpath/javax/swing/plaf/multi/MultiTabbedPaneUI.java,
	classpath/javax/swing/plaf/multi/MultiLookAndFeel.java,
	classpath/javax/swing/plaf/metal/MetalSliderUI.java,
	classpath/javax/swing/plaf/metal/MetalIconFactory.java,
	classpath/javax/swing/plaf/metal/MetalComboBoxIcon.java,
	classpath/javax/swing/plaf/metal/MetalTabbedPaneUI.java,
	classpath/javax/swing/plaf/metal/MetalLookAndFeel.java,
	classpath/javax/swing/plaf/metal/MetalCheckBoxUI.java,
	classpath/javax/swing/plaf/metal/MetalSeparatorUI.java,
	classpath/javax/swing/plaf/metal/MetalBorders.java,
	classpath/javax/swing/plaf/metal/MetalSplitPaneDivider.java,
	classpath/javax/swing/plaf/metal/MetalScrollBarUI.java,
	classpath/javax/swing/plaf/metal/MetalRootPaneUI.java,
	classpath/javax/swing/plaf/metal/MetalInternalFrameUI.java,
	classpath/javax/swing/plaf/metal/MetalRadioButtonUI.java,
	classpath/javax/swing/plaf/metal/MetalToolTipUI.java,
	classpath/javax/swing/plaf/metal/MetalInternalFrameTitlePane.java,
	classpath/javax/swing/plaf/metal/MetalFileChooserUI.java,
	classpath/javax/swing/plaf/metal/MetalUtils.java,
	classpath/javax/swing/plaf/metal/MetalComboBoxButton.java,
	classpath/javax/swing/plaf/metal/MetalPopupMenuSeparatorUI.java,
	classpath/javax/swing/plaf/metal/MetalButtonUI.java,
	classpath/javax/swing/JPopupMenu.java,
	classpath/javax/swing/JProgressBar.java,
	classpath/javax/swing/WindowConstants.java,
	classpath/javax/swing/JFrame.java,
	classpath/javax/swing/JFileChooser.java,
	classpath/javax/swing/JComboBox.java,
	classpath/javax/swing/event/EventListenerList.java,
	classpath/javax/swing/ListSelectionModel.java,
	classpath/javax/swing/JScrollBar.java,
	classpath/java/text/SimpleDateFormat.java,
	classpath/java/text/NumberFormat.java,
	classpath/java/text/class-dependencies.conf,
	classpath/java/awt/image/ColorModel.java,
	classpath/java/awt/image/BufferedImage.java,
	classpath/java/awt/Window.java,
	classpath/java/awt/ContainerOrderFocusTraversalPolicy.java,
	classpath/java/awt/LightweightDispatcher.java,
	classpath/java/awt/EventDispatchThread.java,
	classpath/java/awt/BasicStroke.java,
	classpath/java/awt/ColorPaintContext.java,
	classpath/java/awt/Container.java,
	classpath/java/awt/TexturePaint.java,
	classpath/java/awt/Component.java, classpath/java/awt/Font.java,
	classpath/java/awt/GraphicsConfiguration.java,
	classpath/java/awt/DefaultKeyboardFocusManager.java,
	classpath/java/awt/print/PrinterJob.java,
	classpath/java/awt/im/InputContext.java,
	classpath/java/awt/dnd/DragGestureRecognizer.java,
	classpath/java/awt/Toolkit.java,
	classpath/java/awt/font/GraphicAttribute.java,
	classpath/java/awt/font/ImageGraphicAttribute.java,
	classpath/java/awt/font/GlyphVector.java,
	classpath/java/awt/font/GlyphMetrics.java,
	classpath/java/awt/font/ShapeGraphicAttribute.java,
	classpath/java/awt/Graphics2D.java,
	classpath/include/gnu_java_awt_peer_gtk_GdkGraphicsEnvironment.h,
	classpath/include/gnu_java_awt_peer_gtk_ComponentGraphics.h,
	classpath/include/gnu_java_awt_peer_gtk_CairoGraphics2D.h,
	classpath/include/gnu_java_awt_peer_gtk_FreetypeGlyphVector.h,
	classpath/include/gnu_java_awt_peer_gtk_GtkCanvasPeer.h,
	classpath/include/config.h.in,
	classpath/include/gnu_java_awt_peer_gtk_GdkTextLayout.h,
	classpath/include/gnu_java_awt_peer_gtk_GtkComponentPeer.h,
	classpath/include/gnu_java_awt_peer_gtk_GdkFontPeer.h,
	classpath/include/gnu_java_awt_peer_gtk_ComponentGraphicsCopy.h,
	classpath/include/gnu_java_awt_peer_gtk_GtkVolatileImage.h,
	classpath/include/gnu_java_awt_peer_gtk_GtkImage.h,
	classpath/include/gnu_java_awt_peer_gtk_CairoSurface.h,
	classpath/include/gnu_java_awt_peer_gtk_GdkScreenGraphicsDevice.h:
	Merge from GNU Classpath HEAD.

From-SVN: r114510

1 files changed, 212 insertions, 10 deletions

diff --git a/libjava/classpath/java/awt/Graphics2D.java b/libjava/classpath/java/awt/Graphics2D.java
index 3faa9dc0c66..b3ecbc58a98 100644
--- a/libjava/classpath/java/awt/Graphics2D.java
+++ b/libjava/classpath/java/awt/Graphics2D.java
@@ -1,4 +1,4 @@
-/* Copyright (C) 2000, 2002, 2004  Free Software Foundation
+/* Copyright (C) 2000, 2002, 2004, 2006,  Free Software Foundation
 
 This file is part of GNU Classpath.
 
@@ -45,10 +45,35 @@ import java.awt.image.BufferedImageOp;
 import java.awt.image.ImageObserver;
 import java.awt.image.RenderedImage;
 import java.awt.image.renderable.RenderableImage;
+import java.awt.print.PageFormat;
+import java.awt.print.Printable;
 import java.text.AttributedCharacterIterator;
 import java.util.Map;
 
 /**
+ * An abstract class defining a device independent two-dimensional vector 
+ * graphics API.  Concrete subclasses implement this API for output of 
+ * vector graphics to: (*)
+ * <p>
+ * <ul>
+ * <li>a {@link javax.swing.JComponent} - in the 
+ *     {@link javax.swing.JComponent#paint(Graphics)} method, the incoming 
+ *     {@link Graphics} should always be an instance of 
+ *     <code>Graphics2D</code> (*);</li> 
+ * <li>a {@link BufferedImage} - see 
+ *     {@link BufferedImage#createGraphics()} (*);</li>
+ * <li>a {@link java.awt.print.PrinterJob} - in the 
+ *     {@link Printable#print(Graphics, PageFormat, int)} method, the incoming
+ *     {@link Graphics} should always be an instance of <code>Graphics2D</code>
+ *     (*).</li>
+ * </ul>
+ * <p>
+ * (*) Support for this API is not fully implemented in GNU Classpath yet.
+ * <p>
+ * Third party libraries provide support for output to other formats via this 
+ * API, including encapsulated postscript (EPS), portable document format (PDF),
+ * and scalable vector graphics (SVG).
+ * 
  * @author Rolf W. Rasmussen (rolfwr@ii.uib.no)
  */
 public abstract class Graphics2D extends Graphics
@@ -70,6 +95,14 @@ public abstract class Graphics2D extends Graphics
     super.fill3DRect(x, y, width, height, raised);
   }
 
+  /**
+   * Draws an outline around a shape using the current stroke and paint.
+   * 
+   * @param shape  the shape (<code>null</code> not permitted).
+   * 
+   * @see #getStroke()
+   * @see #getPaint()
+   */
   public abstract void draw(Shape shape);
 
   public abstract boolean drawImage(Image image, AffineTransform xform,
@@ -86,18 +119,57 @@ public abstract class Graphics2D extends Graphics
   public abstract void drawRenderableImage(RenderableImage image,
                                            AffineTransform xform);
 
+  /**
+   * Draws a string at the specified location, using the current font.
+   * 
+   * @param text  the string to draw.
+   * @param x  the x-coordinate.
+   * @param y  the y-coordinate.
+   * 
+   * @see Graphics#setFont(Font)
+   */
   public abstract void drawString(String text, int x, int y);
 
+  /**
+   * Draws a string at the specified location, using the current font.
+   * 
+   * @param text  the string to draw.
+   * @param x  the x-coordinate.
+   * @param y  the y-coordinate.
+   * 
+   * @see Graphics#setFont(Font)
+   */
   public abstract void drawString(String text, float x, float y);
     
+  /**
+   * Draws an attributed string at the specified location.
+   * 
+   * @param iterator  the source of the attributed text.
+   * @param x  the x-coordinate.
+   * @param y  the y-coordinate.
+   */
   public abstract void drawString(AttributedCharacterIterator iterator,
                                   int x, int y);
 
+  /**
+   * Draws an attributed string at the specified location.
+   * 
+   * @param iterator  the source of the attributed text.
+   * @param x  the x-coordinate.
+   * @param y  the y-coordinate.
+   */
   public abstract void drawString(AttributedCharacterIterator iterator,
 				  float x, float y);
 
-  // public abstract void drawGlyphVector(GlyphVector g, float x, float y);
-
+  /**
+   * Fills the interior of the specified <code>shape</code> using the current
+   * paint.
+   * 
+   * @param shape  the shape to fill (<code>null</code> not permitted).
+   * 
+   * @see #draw(Shape)
+   * @see #getPaint()
+   */
   public abstract void fill(Shape shape);
     
   public abstract boolean hit(Rectangle rect, Shape text,
@@ -105,21 +177,72 @@ public abstract class Graphics2D extends Graphics
 
   public abstract GraphicsConfiguration getDeviceConfiguration();
 
+  /**
+   * Sets the current compositing rule.
+   * 
+   * @param comp  the composite.
+   * 
+   * @see #getComposite()
+   */
   public abstract void setComposite(Composite comp);
-    
+
+  /**
+   * Sets the paint to be used for subsequent drawing operations.
+   * 
+   * @param paint  the paint (<code>null</code> not permitted).
+   * 
+   * @see #getPaint()
+   */
   public abstract void setPaint(Paint paint);
 
+  /**
+   * Sets the stroke to be used for subsequent drawing operations.
+   * 
+   * @param stroke  the stroke (<code>null</code> not permitted).
+   * 
+   * @see #getStroke()
+   */
   public abstract void setStroke(Stroke stroke);
 
+  /**
+   * Adds or updates a hint in the current rendering hints table.
+   * 
+   * @param hintKey  the hint key.
+   * @param hintValue  the hint value.
+   */
   public abstract void setRenderingHint(RenderingHints.Key hintKey,
                                         Object hintValue);
 
+  /**
+   * Returns the current value of a rendering hint.
+   * 
+   * @param hintKey  the key for the hint.
+   * 
+   * @return The value for the specified hint.
+   */
   public abstract Object getRenderingHint(RenderingHints.Key hintKey);
   
+  /**
+   * Replaces the current rendering hints with the supplied hints.
+   * 
+   * @param hints  the hints.
+   * 
+   * @see #addRenderingHints(Map)
+   */
   public abstract void setRenderingHints(Map hints);
 
+  /**
+   * Adds/updates the rendering hint.
+   * 
+   * @param hints  the hints to add or update.
+   */
   public abstract void addRenderingHints(Map hints);
 
+  /**
+   * Returns the current rendering hints.
+   * 
+   * @return The current rendering hints.
+   */
   public abstract RenderingHints getRenderingHints();
 
   public abstract void translate(int x, int y);
@@ -134,25 +257,104 @@ public abstract class Graphics2D extends Graphics
 
   public abstract void shear(double shearX, double shearY);
 
-  public abstract void transform(AffineTransform Tx);
+  /**
+   * Sets the current transform to a concatenation of <code>transform</code>
+   * and the existing transform.
+   * 
+   * @param transform  the transform.
+   */
+  public abstract void transform(AffineTransform transform);
   
-  public abstract void setTransform(AffineTransform Tx);
-
+  /**
+   * Sets the current transform.  If the caller specifies a <code>null</code>
+   * transform, this method should set the current transform to the 
+   * identity transform.
+   * 
+   * @param transform  the transform (<code>null</code> permitted).
+   * 
+   * @see #getTransform()
+   */
+  public abstract void setTransform(AffineTransform transform);
+
+  /**
+   * Returns the current transform.
+   * 
+   * @return The current transform.
+   * 
+   * @see #setTransform(AffineTransform)
+   */
   public abstract AffineTransform getTransform();
 
+  /**
+   * Returns the current paint.
+   * 
+   * @return The current paint.
+   * 
+   * @see #setPaint(Paint)
+   */
   public abstract Paint getPaint();
 
+  /**
+   * Returns the current compositing rule.
+   * 
+   * @return The current compositing rule.
+   * 
+   * @see #setComposite(Composite)
+   */
   public abstract Composite getComposite();
 
+  /**
+   * Sets the background color (used by the 
+   * {@link Graphics#clearRect(int, int, int, int)} method).
+   * 
+   * @param color  the color.
+   * 
+   * @see #getBackground()
+   */
   public abstract void setBackground(Color color);
 
+  /**
+   * Returns the color used by the 
+   * {@link Graphics#clearRect(int, int, int, int)} method.
+   * 
+   * @return The background color.
+   * 
+   * @see #setBackground(Color)
+   */
   public abstract Color getBackground();
 
+  /**
+   * Returns the current stroke.
+   * 
+   * @return The current stroke.
+   * 
+   * @see #setStroke(Stroke)
+   */
   public abstract Stroke getStroke();    
 
+  /**
+   * Sets the clip region to the intersection of the current clipping region 
+   * and <code>s</code>.
+   * 
+   * @param s  the shape to intersect with the current clipping region.
+   * 
+   * @see Graphics#setClip(Shape)
+   */
   public abstract void clip(Shape s);
 
-  public abstract FontRenderContext getFontRenderContext ();
-
-  public abstract void drawGlyphVector (GlyphVector g, float x, float y);
+  /**
+   * Returns the font render context.
+   * 
+   * @return The font render context.
+   */
+  public abstract FontRenderContext getFontRenderContext();
+
+  /**
+   * Draws a glyph vector at the specified location.
+   * 
+   * @param g  the glyph vector.
+   * @param x  the x-coordinate.
+   * @param y  the y-coordinate.
+   */
+  public abstract void drawGlyphVector(GlyphVector g, float x, float y);
 }