From f727e882fa7bdd4affdebc07ce233b2707c56e5b Mon Sep 17 00:00:00 2001 From: Joe Darcy Date: Tue, 14 Jan 2014 23:10:41 -0800 Subject: [PATCH] 8031467: Fix doclint missing issues in java.awt.{dnd[.peer], datatransfer} Reviewed-by: pchelko --- .../java/awt/datatransfer/Clipboard.java | 11 +++++-- .../java/awt/datatransfer/DataFlavor.java | 29 +++++++++++++++++-- .../awt/datatransfer/StringSelection.java | 1 + .../awt/datatransfer/SystemFlavorMap.java | 5 +++- .../java/awt/datatransfer/Transferable.java | 3 +- .../classes/java/awt/dnd/DragSource.java | 2 ++ .../classes/java/awt/dnd/DropTarget.java | 6 ++-- .../awt/dnd/peer/DragSourceContextPeer.java | 8 ++++- .../awt/dnd/peer/DropTargetContextPeer.java | 12 +++++++- 9 files changed, 66 insertions(+), 11 deletions(-) diff --git a/jdk/src/share/classes/java/awt/datatransfer/Clipboard.java b/jdk/src/share/classes/java/awt/datatransfer/Clipboard.java index cce9c74c192..d1926960325 100644 --- a/jdk/src/share/classes/java/awt/datatransfer/Clipboard.java +++ b/jdk/src/share/classes/java/awt/datatransfer/Clipboard.java @@ -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 @@ public class Clipboard { String name; + /** + * The owner of the clipboard. + */ protected ClipboardOwner owner; + /** + * Contents of the clipboard. + */ protected Transferable contents; /** @@ -75,7 +81,7 @@ public class Clipboard { /** * Creates a clipboard object. - * + * @param name for the clipboard * @see java.awt.Toolkit#getSystemClipboard */ public Clipboard(String name) { @@ -84,6 +90,7 @@ public class Clipboard { /** * Returns the name of this clipboard object. + * @return the name of this clipboard object * * @see java.awt.Toolkit#getSystemClipboard */ diff --git a/jdk/src/share/classes/java/awt/datatransfer/DataFlavor.java b/jdk/src/share/classes/java/awt/datatransfer/DataFlavor.java index 90789edc97c..cbf172ba05c 100644 --- a/jdk/src/share/classes/java/awt/datatransfer/DataFlavor.java +++ b/jdk/src/share/classes/java/awt/datatransfer/DataFlavor.java @@ -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 @@ public class DataFlavor implements Externalizable, Cloneable { /** * Does the DataFlavor 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 @@ public class DataFlavor implements Externalizable, Cloneable { /** * Does the DataFlavor represent a * java.io.InputStream? + * @return whether or not this {@code DataFlavor} represent a + * {@code java.io.InputStream} */ - public boolean isRepresentationClassInputStream() { return ioInputStreamClass.isAssignableFrom(representationClass); } @@ -1211,6 +1220,9 @@ public class DataFlavor implements Externalizable, Cloneable { * Returns whether the representation class for this * DataFlavor is java.io.Reader 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 @@ public class DataFlavor implements Externalizable, Cloneable { * Returns whether the representation class for this * DataFlavor is java.nio.CharBuffer 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 @@ public class DataFlavor implements Externalizable, Cloneable { * Returns whether the representation class for this * DataFlavor is java.nio.ByteBuffer 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 @@ public class DataFlavor implements Externalizable, Cloneable { * * 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 @@ public class DataFlavor implements Externalizable, Cloneable { * * This method is never invoked by this implementation from 1.1 onwards. * + * @param mimeType the mime type + * @return the mime type * @deprecated */ @Deprecated diff --git a/jdk/src/share/classes/java/awt/datatransfer/StringSelection.java b/jdk/src/share/classes/java/awt/datatransfer/StringSelection.java index 6036bd821da..c65f04fbaa7 100644 --- a/jdk/src/share/classes/java/awt/datatransfer/StringSelection.java +++ b/jdk/src/share/classes/java/awt/datatransfer/StringSelection.java @@ -57,6 +57,7 @@ public class StringSelection implements Transferable, ClipboardOwner { /** * Creates a Transferable capable of transferring * the specified String. + * @param data the string to be transferred */ public StringSelection(String data) { this.data = data; diff --git a/jdk/src/share/classes/java/awt/datatransfer/SystemFlavorMap.java b/jdk/src/share/classes/java/awt/datatransfer/SystemFlavorMap.java index 86713ad3c5a..8c94ca5b15f 100644 --- a/jdk/src/share/classes/java/awt/datatransfer/SystemFlavorMap.java +++ b/jdk/src/share/classes/java/awt/datatransfer/SystemFlavorMap.java @@ -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 @@ public final class SystemFlavorMap implements FlavorMap, FlavorTable { /** * 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 @@ public final class SystemFlavorMap implements FlavorMap, FlavorTable { * @param nat the String to decode * @return the decoded DataFlavor, or null if * nat is not an encoded String native + * @throws ClassNotFoundException if the class of the data flavor + * is not loaded */ public static DataFlavor decodeDataFlavor(String nat) throws ClassNotFoundException diff --git a/jdk/src/share/classes/java/awt/datatransfer/Transferable.java b/jdk/src/share/classes/java/awt/datatransfer/Transferable.java index 3c5219ddb1d..3ba437748ab 100644 --- a/jdk/src/share/classes/java/awt/datatransfer/Transferable.java +++ b/jdk/src/share/classes/java/awt/datatransfer/Transferable.java @@ -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 @@ public interface Transferable { * 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. diff --git a/jdk/src/share/classes/java/awt/dnd/DragSource.java b/jdk/src/share/classes/java/awt/dnd/DragSource.java index d44733b71d8..ac9b15a2051 100644 --- a/jdk/src/share/classes/java/awt/dnd/DragSource.java +++ b/jdk/src/share/classes/java/awt/dnd/DragSource.java @@ -495,6 +495,7 @@ public class DragSource implements Serializable { * and DragGestureListener on * the newly created object. *

+ * @param the type of {@code DragGestureRecognizer} to create * @param recognizerAbstractClass the requested abstract type * @param actions the permitted source drag actions * @param c the Component target @@ -669,6 +670,7 @@ public class DragSource implements Serializable { * FooListeners are registered using the * addFooListener method. * + * @param the type of listener objects * @param listenerType the type of listeners requested; this parameter * should specify an interface that descends from * java.util.EventListener diff --git a/jdk/src/share/classes/java/awt/dnd/DropTarget.java b/jdk/src/share/classes/java/awt/dnd/DropTarget.java index ad672936078..9f5462a320b 100644 --- a/jdk/src/share/classes/java/awt/dnd/DropTarget.java +++ b/jdk/src/share/classes/java/awt/dnd/DropTarget.java @@ -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 @@ public class DropTarget implements DropTargetListener, Serializable { * 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 @@ public class DropTarget implements DropTargetListener, Serializable { /** * create an embedded autoscroller - *

+ * * @param c the Component * @param p the Point + * @return an embedded autoscroller */ protected DropTargetAutoScroller createDropTargetAutoScroller(Component c, Point p) { diff --git a/jdk/src/share/classes/java/awt/dnd/peer/DragSourceContextPeer.java b/jdk/src/share/classes/java/awt/dnd/peer/DragSourceContextPeer.java index 2965bec4dd4..8d69a6163b7 100644 --- a/jdk/src/share/classes/java/awt/dnd/peer/DragSourceContextPeer.java +++ b/jdk/src/share/classes/java/awt/dnd/peer/DragSourceContextPeer.java @@ -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 @@ public interface DragSourceContextPeer { /** * 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; diff --git a/jdk/src/share/classes/java/awt/dnd/peer/DropTargetContextPeer.java b/jdk/src/share/classes/java/awt/dnd/peer/DropTargetContextPeer.java index 34205c6cdc5..de74e8fb5f0 100644 --- a/jdk/src/share/classes/java/awt/dnd/peer/DropTargetContextPeer.java +++ b/jdk/src/share/classes/java/awt/dnd/peer/DropTargetContextPeer.java @@ -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 @@ public interface DropTargetContextPeer { /** * 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 @@ public interface DropTargetContextPeer { /** * accept the Drag + * @param dragAction the drag action */ void acceptDrag(int dragAction); @@ -92,6 +100,7 @@ public interface DropTargetContextPeer { /** * accept the Drop + * @param dropAction the drop action */ void acceptDrop(int dropAction); @@ -104,6 +113,7 @@ public interface DropTargetContextPeer { /** * signal complete + * @param success the signal */ void dropComplete(boolean success);