<AWT Dev> JDK 9 RFR of JDK-8031467: Fix doclint missing issues in java.awt.{dnd[.peer], datatransfer}
Joe Darcy
joe.darcy at oracle.com
Thu Jan 9 18:05:47 PST 2014
Hello,
Please review the patch below which adds in the javadoc missing for
elements in java.awt.datatransfer, java.awt.dnd, and java.awt.dnd.peer
packages.
Patch below; webrev at
http://cr.openjdk.java.net/~darcy/8031467.0/
thanks,
-Joe
--- old/src/share/classes/java/awt/datatransfer/Clipboard.java
2014-01-09 18:04:43.000000000 -0800
+++ new/src/share/classes/java/awt/datatransfer/Clipboard.java
2014-01-09 18:04:43.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights
reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -54,7 +54,13 @@
String name;
+ /**
+ * The owner of the clipboard.
+ */
protected ClipboardOwner owner;
+ /**
+ * Contents of the clipboard.
+ */
protected Transferable contents;
/**
@@ -75,7 +81,7 @@
/**
* Creates a clipboard object.
- *
+ * @param name for the clipboard
* @see java.awt.Toolkit#getSystemClipboard
*/
public Clipboard(String name) {
@@ -84,6 +90,7 @@
/**
* Returns the name of this clipboard object.
+ * @return the name of this clipboard object
*
* @see java.awt.Toolkit#getSystemClipboard
*/
--- old/src/share/classes/java/awt/datatransfer/DataFlavor.java
2014-01-09 18:04:44.000000000 -0800
+++ new/src/share/classes/java/awt/datatransfer/DataFlavor.java
2014-01-09 18:04:43.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2006, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights
reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -1184,16 +1184,24 @@
/**
* Does the <code>DataFlavor</code> represent a serialized object?
+ * @return whether or not a serialized object is represented
*/
-
public boolean isMimeTypeSerializedObject() {
return isMimeTypeEqual(javaSerializedObjectMimeType);
}
+ /**
+ * Returns the default representation class.
+ * @return the default representation class
+ */
public final Class<?> getDefaultRepresentationClass() {
return ioInputStreamClass;
}
+ /**
+ * Returns the name of the default representation class.
+ * @return the name of the default representation class
+ */
public final String getDefaultRepresentationClassAsString() {
return getDefaultRepresentationClass().getName();
}
@@ -1201,8 +1209,9 @@
/**
* Does the <code>DataFlavor</code> represent a
* <code>java.io.InputStream</code>?
+ * @return whether or not this {@code DataFlavor} represent a
+ * {@codejava.io.InputStream}
*/
-
public boolean isRepresentationClassInputStream() {
return ioInputStreamClass.isAssignableFrom(representationClass);
}
@@ -1211,6 +1220,9 @@
* Returns whether the representation class for this
* <code>DataFlavor</code> is <code>java.io.Reader</code> or a
subclass
* thereof.
+ * @return whether or not the representation class for this
+ * {@code DataFlavor} is {@code java.io.Reader} or a subclass
+ * thereof
*
* @since 1.4
*/
@@ -1222,6 +1234,9 @@
* Returns whether the representation class for this
* <code>DataFlavor</code> is <code>java.nio.CharBuffer</code> or a
* subclass thereof.
+ * @return whether or not the representation class for this
+ * {@code DataFlavor} is {@code java.nio.CharBuffer} or a subclass
+ * thereof
*
* @since 1.4
*/
@@ -1233,6 +1248,9 @@
* Returns whether the representation class for this
* <code>DataFlavor</code> is <code>java.nio.ByteBuffer</code> or a
* subclass thereof.
+ * @return whether or not the representation class for this
+ * {@code DataFlavor} is {@code java.nio.ByteBuffer} or a subclass
+ * thereof
*
* @since 1.4
*/
@@ -1408,6 +1426,9 @@
*
* This method is never invoked by this implementation from 1.1
onwards.
*
+ * @param parameterName the parameter name
+ * @param parameterValue the parameter value
+ * @return the parameter value
* @deprecated
*/
@Deprecated
@@ -1424,6 +1445,8 @@
*
* This method is never invoked by this implementation from 1.1
onwards.
*
+ * @param mimeType the mime type
+ * @return the mime type
* @deprecated
*/
@Deprecated
--- old/src/share/classes/java/awt/datatransfer/StringSelection.java
2014-01-09 18:04:44.000000000 -0800
+++ new/src/share/classes/java/awt/datatransfer/StringSelection.java
2014-01-09 18:04:44.000000000 -0800
@@ -57,6 +57,7 @@
/**
* Creates a <code>Transferable</code> capable of transferring
* the specified <code>String</code>.
+ * @param data the string to be transferred
*/
public StringSelection(String data) {
this.data = data;
--- old/src/share/classes/java/awt/datatransfer/SystemFlavorMap.java
2014-01-09 18:04:45.000000000 -0800
+++ new/src/share/classes/java/awt/datatransfer/SystemFlavorMap.java
2014-01-09 18:04:44.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights
reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -181,6 +181,7 @@
/**
* Returns the default FlavorMap for this thread's ClassLoader.
+ * @return the default FlavorMap for this thread's ClassLoader
*/
public static FlavorMap getDefaultFlavorMap() {
ClassLoader contextClassLoader =
@@ -1309,6 +1310,8 @@
* @param nat the <code>String</code> to decode
* @return the decoded <code>DataFlavor</code>, or
<code>null</code> if
* nat is not an encoded <code>String</code> native
+ * @throws ClassNotFoundException if the class of the data flavor
+ * is not loaded
*/
public static DataFlavor decodeDataFlavor(String nat)
throws ClassNotFoundException
--- old/src/share/classes/java/awt/datatransfer/Transferable.java
2014-01-09 18:04:45.000000000 -0800
+++ new/src/share/classes/java/awt/datatransfer/Transferable.java
2014-01-09 18:04:45.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 1996, 2014, Oracle and/or its affiliates. All rights
reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -62,6 +62,7 @@
* of the object returned is defined by the representation class
of the flavor.
*
* @param flavor the requested flavor for the data
+ * @return an object which represents the data to be transferred
* @see DataFlavor#getRepresentationClass
* @exception IOException if the data is no longer
available
* in the requested flavor.
--- old/src/share/classes/java/awt/dnd/DragSource.java 2014-01-09
18:04:46.000000000 -0800
+++ new/src/share/classes/java/awt/dnd/DragSource.java 2014-01-09
18:04:46.000000000 -0800
@@ -495,6 +495,7 @@
* and <code>DragGestureListener</code> on
* the newly created object.
* <P>
+ * @param <T> the type of {@code DragGestureRecognizer} to create
* @param recognizerAbstractClass the requested abstract type
* @param actions the permitted source drag actions
* @param c the <code>Component</code> target
@@ -669,6 +670,7 @@
* <code><em>Foo</em>Listener</code>s are registered using the
* <code>add<em>Foo</em>Listener</code> method.
*
+ * @param <T> the type of listener objects
* @param listenerType the type of listeners requested; this parameter
* should specify an interface that descends from
* <code>java.util.EventListener</code>
--- old/src/share/classes/java/awt/dnd/DropTarget.java 2014-01-09
18:04:46.000000000 -0800
+++ new/src/share/classes/java/awt/dnd/DropTarget.java 2014-01-09
18:04:46.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights
reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -566,6 +566,7 @@
* DropTargetContextPeer as a drag operation encounters this
* DropTarget. Accessing the Context while no Drag is current
* has undefined results.
+ * @return the DropTargetContext associated with this DropTarget
*/
protected DropTargetContext createDropTargetContext() {
@@ -766,9 +767,10 @@
/**
* create an embedded autoscroller
- * <P>
+ *
* @param c the <code>Component</code>
* @param p the <code>Point</code>
+ * @return an embedded autoscroller
*/
protected DropTargetAutoScroller
createDropTargetAutoScroller(Component c, Point p) {
--- old/src/share/classes/java/awt/dnd/peer/DragSourceContextPeer.java
2014-01-09 18:04:47.000000000 -0800
+++ new/src/share/classes/java/awt/dnd/peer/DragSourceContextPeer.java
2014-01-09 18:04:46.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights
reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -47,18 +47,24 @@
/**
* start a drag
+ * @param dsc the DragSourceContext
+ * @param c the cursor
+ * @param dragImage the image to be dragged
+ * @param imageOffset the offset
*/
void startDrag(DragSourceContext dsc, Cursor c, Image dragImage,
Point imageOffset) throws InvalidDnDOperationException;
/**
* return the current drag cursor
+ * @return the current drag cursor
*/
Cursor getCursor();
/**
* set the current drag cursor
+ * @param c the cursor
*/
void setCursor(Cursor c) throws InvalidDnDOperationException;
--- old/src/share/classes/java/awt/dnd/peer/DropTargetContextPeer.java
2014-01-09 18:04:47.000000000 -0800
+++ new/src/share/classes/java/awt/dnd/peer/DropTargetContextPeer.java
2014-01-09 18:04:47.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1997, 2007, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights
reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -44,35 +44,42 @@
/**
* update the peer's notion of the Target's actions
+ * @param actions the actions
*/
void setTargetActions(int actions);
/**
* get the current Target actions
+ * @return the current Target actions
*/
int getTargetActions();
/**
* get the DropTarget associated with this peer
+ * @return the DropTarget associated with this peer
*/
DropTarget getDropTarget();
/**
* get the (remote) DataFlavors from the peer
+ * @return the (remote) DataFlavors from the peer
*/
DataFlavor[] getTransferDataFlavors();
/**
* get an input stream to the remote data
+ * @return an input stream to the remote data
*/
Transferable getTransferable() throws InvalidDnDOperationException;
/**
+ * Return whether or not the DragSource Transferable is in the
+ * same JVM as the Target.
* @return if the DragSource Transferable is in the same JVM as
the Target
*/
@@ -80,6 +87,7 @@
/**
* accept the Drag
+ * @param dragAction the drag action
*/
void acceptDrag(int dragAction);
@@ -92,6 +100,7 @@
/**
* accept the Drop
+ * @param dropAction the drop action
*/
void acceptDrop(int dropAction);
@@ -104,6 +113,7 @@
/**
* signal complete
+ * @param success the signal
*/
void dropComplete(boolean success);
More information about the awt-dev
mailing list