updating javadoc for DNDv2047g

7 files changed, 289 insertions, 76 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
index 26e06f445e..e828e9f98b 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -22,8 +22,98 @@ import org.eclipse.swt.internal.photon.*;
  * <p>If the data you are converting <b>does not</b> map to a 

  * <code>byte[]</code>, you should sub-class <code>Transfer</code> directly 

  * and do your own mapping to a platform data type.</p>

+ * 

+ * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers

+ * data defined by the class <code>MyType</code>.</p>

+ * 

+ * <pre><code>

+ * public class MyType {

+ *	public String fileName;

+ *	public long fileLength;

+ *	public long lastModified;

+ * }

+ * </code></pre>

+ * 

+ * <code><pre>

+ * public class MyTypeTransfer extends ByteArrayTransfer {

+ *	

+ *	private static final String MYTYPENAME = "my_type_name";

+ *	private static final int MYTYPEID = registerType(MYTYPENAME);

+ *	private static MyTypeTransfer _instance = new MyTypeTransfer();

+ * 

+ * private MyTypeTransfer() {}

+ * 

+ * public static MyTypeTransfer getInstance () {

+ * 	return _instance;

+ * }

+ * public void javaToNative (Object object, TransferData transferData) {

+ * 	if (object == null || !(object instanceof MyType[])) return;

+ * 	

+ * 	if (isSupportedType(transferData)) {

+ * 		MyType[] myTypes = (MyType[]) object;	

+ * 		try {

+ * 			// write data to a byte array and then ask super to convert to pMedium

+ * 			ByteArrayOutputStream out = new ByteArrayOutputStream();

+ * 			DataOutputStream writeOut = new DataOutputStream(out);

+ * 			for (int i = 0, length = myTypes.length; i < length;  i++){

+ * 				byte[] buffer = myTypes[i].fileName.getBytes();

+ * 				writeOut.writeInt(buffer.length);

+ * 				writeOut.write(buffer);

+ * 				writeOut.writeLong(myTypes[i].fileLength);

+ * 				writeOut.writeLong(myTypes[i].lastModified);

+ * 			}

+ * 			byte[] buffer = out.toByteArray();

+ * 			writeOut.close();

+ * 

+ * 			super.javaToNative(buffer, transferData);

+ * 			

+ * 		} catch (IOException e) {

+ * 		}

+ * 	}

+ * }

+ * public Object nativeToJava(TransferData transferData){	

+ * 

+ * 	if (isSupportedType(transferData)) {

+ * 		

+ * 		byte[] buffer = (byte[])super.nativeToJava(transferData);

+ * 		if (buffer == null) return null;

+ * 		

+ * 		MyType[] myData = new MyType[0];

+ * 		try {

+ * 			ByteArrayInputStream in = new ByteArrayInputStream(buffer);

+ * 			DataInputStream readIn = new DataInputStream(in);

+ * 			while(readIn.available() > 20) {

+ * 				MyType datum = new MyType();

+ * 				int size = readIn.readInt();

+ * 				byte[] name = new byte[size];

+ * 				readIn.read(name);

+ * 				datum.fileName = new String(name);

+ * 				datum.fileLength = readIn.readLong();

+ * 				datum.lastModified = readIn.readLong();

+ * 				MyType[] newMyData = new MyType[myData.length + 1];

+ * 				System.arraycopy(myData, 0, newMyData, 0, myData.length);

+ * 				newMyData[myData.length] = datum;

+ * 				myData = newMyData;

+ * 			}

+ * 			readIn.close();

+ * 		} catch (IOException ex) {

+ * 			return null;

+ * 		}

+ * 		return myData;

+ * 	}

+ * 

+ * 	return null;

+ * }

+ * protected String[] getTypeNames(){

+ * 	return new String[]{MYTYPENAME};

+ * }

+ * protected int[] getTypeIds(){

+ * 	return new int[] {MYTYPEID};

+ * }

+ * }

  */
 public abstract class ByteArrayTransfer extends Transfer {

+	

 public TransferData[] getSupportedTypes(){

 	int[] types = getTypeIds();

 	TransferData[] data = new TransferData[types.length];

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java
index 64235e9262..870a1158d8 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java
@@ -13,7 +13,7 @@ import org.eclipse.swt.internal.photon.*;
 import org.eclipse.swt.widgets.*;

 

 /**

- * The <code>Clipboard</code> provides a mechanism for copying data from one

+ * The <code>Clipboard</code> provides a mechanism for transferring data from one

  * application to another or within an application.

  * 

  * <p>IMPORTANT: This class is <em>not</em> intended to be subclassed.</p>

@@ -24,6 +24,21 @@ public class Clipboard {
 	private final int MAX_RETRIES = 10;

 

 

+/**

+ * Constructs a new instance of this class.  Creating an instance of a Clipboard

+ * may cause system resources to be allocated depending on the platform.  It is therefore

+ * mandatory that the Clipboard instance be disposed when no longer required.

+ *

+ * @param display the display on which to allocate the clipboard

+ *

+ * @exception SWTException <ul>

+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>

+ *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>

+ * </ul>

+ *

+ * @see Clipboard#dispose

+ * @see Clipboard#checkSubclass

+ */

 public Clipboard(Display display) {	

 	checkSubclass ();

 	if (display == null) {

@@ -56,18 +71,23 @@ public void dispose () {
 	display = null;

 }

 /**

- *  Retrieve the data of the specified type currently available on the system clipboard.

+ * Retrieve the data of the specified type currently available on the system clipboard.  Refer to the 

+ * specific subclass of <code>Tramsfer</code> to determine the type of object returned.

  * 

- *  <code><pre>

- * 	Clipboard clipboard = new Clipboard(display);

- *		TextTransfer textTransfer = TextTransfer.getInstance();

- *		String textData = (String)clipboard.getContents(textTransfer);

- * 	if (textData != null) System.out.println("Text is "+textData);

- *		RTFTransfer rtfTransfer = RTFTransfer.getInstance();

- *  	String rtfData = (String)clipboard.getContents(rtfTransfer);

- * 	if (rtfData != null) System.out.println("RTF Text is "+rtfData);

- *		clipboard.dispose();

- * </code></pre>

+ * <p>The following snippet shows text and RTF text being retrieved from the clipboard:</p>

+ * 

+ *    <code><pre>

+ *    Clipboard clipboard = new Clipboard(display);

+ *    TextTransfer textTransfer = TextTransfer.getInstance();

+ *    String textData = (String)clipboard.getContents(textTransfer);

+ *    if (textData != null) System.out.println("Text is "+textData);

+ *    RTFTransfer rtfTransfer = RTFTransfer.getInstance();

+ *    String rtfData = (String)clipboard.getContents(rtfTransfer);

+ *    if (rtfData != null) System.out.println("RTF Text is "+rtfData);

+ *    clipboard.dispose();

+ *    </code></pre>

+ * 

+ * @see Transfer

  * 

  * @param transfer the transfer agent for the type of data being requested

  * 

@@ -201,17 +221,12 @@ public void setContents(Object[] data, Transfer[] transferAgents){
  * Returns a platform specific list of the data types currently available on the 

  * system clipboard.

  * 

- * <p>Note: <code>getAvailableTypeNames</code> is a tool for writing a Transfer 

- * sub-class only.  It should NOT be used within an application because it provides 

+ * <p>Note: <code>getAvailableTypeNames</code> is a utility for writing a Transfer 

+ * sub-class.  It should NOT be used within an application because it provides 

  * platform specific information.</p>

  * 

  * @returns a platform specific list of the data types currently available on the 

  * system clipboard

- */
-/*

- * Note: getAvailableTypeNames is a tool for writing a Transfer sub-class only.  It should

- * NOT be used within an application because it provides platform specfic 

- * information.

  */

 public String[] getAvailableTypeNames() {

 	String[] types = new String[0];

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DragSource.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DragSource.java
index 1bbc18bc61..b9fef5dd2f 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DragSource.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DragSource.java
@@ -14,25 +14,37 @@ import org.eclipse.swt.internal.photon.*;
 

 /**

  *

- * Class <code>DragSource</code> defines the source object for a drag and drop transfer.

+ * <code>DragSource</code> defines the source object for a drag and drop transfer.

  *

- * IMPORTANT: This class is <em>not</em> intended to be subclassed.

- *

- * <p>This class defines the following items:<ul>

- *   <li>the <code>Control</code> that the user clicks on to intiate a drag;

- *   <li>the data that will be transferred on a successful drop; 

- *   <li>and the modes (move, copy, link) of transfer that are allowed.

- * </ul></p>

+ * <p>IMPORTANT: This class is <em>not</em> intended to be subclassed.</p>

+ *  

+ * <p>A drag source is the object which originates a drag and drop operation. For the specified widget, 

+ * it defines the type of data that is available for dragging and the set of operations that can 

+ * be performed on that data.  The operations can be any bit-wise combination of DND.MOVE, DND.COPY or 

+ * DND.LINK.  The type of data that can be transferred is specified by subclasses of Transfer such as 

+ * TextTransfer or FileTransfer.  The type of data transferred can be a predefined system type or it 

+ * can be a type defined by the application.  For instructions on how to define your own transfer type,

+ * refer to <code>ByteArrayTransfer</code>.</p>

  *

  * <p>You may have several DragSources in an application but you can only have one DragSource 

  * per Control.  Data dragged from this DragSource can be dropped on a site within this application 

- * but it can also be dropped on another application such as an external Text editor.</p>

+ * or it can be dropped on another application such as an external Text editor.</p>

  * 

- * <p>The application supplies the content of the data being transferred by implementing the interface

- * <code>DragSourceListener</code> which uses the class <code>DragSourceEvent</code>.  

- * The application is required to take the appropriate action to remove the data from the drag source

- * when a successful move operation occurs.</p>

+ * <p>The application supplies the content of the data being transferred by implementing the

+ * <code>DragSourceListener</code> and associating it with the DragSource via DragSource#addDragListener.</p>

+ * 

+ * <p>When a successful move operation occurs, the application is required to take the appropriate 

+ * action to remove the data from its display and remove any associated operating system resources or

+ * internal references.  Typically in a move operation, the drop target makes a copy of the data 

+ * and the drag source deletes the original.  However, sometimes copying the data can take a long 

+ * time (such as copying a large file).  Therefore, on some platforms, the drop target may actually 

+ * move the data in the operating system rather than make a copy.  This is usually only done in 

+ * file transfers.  In this case, the drag source is informed in the DragEnd event that a

+ * DROP_TARGET_MOVE was performed.  It is the responsibility of the drag source at this point to clean 

+ * up its displayed information.  No action needs to be taken on the operating system resources.</p>

  *

+ * <p> The following example shows a Label widget that allows text to be dragged from it.</p>

+ * 

  * <code><pre>

  *	// Enable a label as a Drag Source

  *	Label label = new Label(shell, SWT.NONE);

@@ -72,8 +84,8 @@ import org.eclipse.swt.internal.photon.*;
  *

  *

  * <dl>

- *	<dt><b>Styles</b> <dd>DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK 

- *	<dt><b>Events</b> <dd>DND.DragEnd, DND.DragSetData

+ *	<dt><b>Styles</b></dt> <dd>DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK</dd>

+ *	<dt><b>Events</b></dt> <dd>DND.DragStart, DND.DragSetData, DND.DragEnd</dd>

  * </dl>

  */

 public class DragSource extends Widget {

@@ -93,12 +105,20 @@ public class DragSource extends Widget {
 

 /**

  * Creates a new <code>DragSource</code> to handle dragging from the specified <code>Control</code>.

- * 

- * @param control the <code>Control</code> that the user clicks on to initiate the drag

+ * Creating an instance of a DragSource may cause system resources to be allocated depending on the platform.  

+ * It is therefore mandatory that the DragSource instance be disposed when no longer required.

  *

+ * @param control the <code>Control</code> that the user clicks on to initiate the drag

  * @param style the bitwise OR'ing of allowed operations; this may be a combination of any of 

  *					DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK

+ * 

+ * @exception SWTException <ul>

+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>

+ *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>

+ * </ul>

  *

+ * @see DragSource#dispose

+ * @see DragSource#checkSubclass

  * @see DND#DROP_NONE

  * @see DND#DROP_COPY

  * @see DND#DROP_MOVE

@@ -131,15 +151,35 @@ public DragSource(Control control, int style) {
 		}

 	});

 }

-/**	 

- * Adds the listener to receive events.

+

+/**

+ * Adds the listener to the collection of listeners who will

+ * be notified when a drag and drop operation is in progress, by sending

+ * it one of the messages defined in the <code>DragSourceListener</code>

+ * interface.

+ * 

+ * <p><ul>

+ * <li><code>dragStart</code> is called when the user has begun the actions required to drag the widget. 

+ * This event gives the application the chance to decide if a drag should be started.

+ * <li><code>dragSetData</code> is called when the data is required from the drag source.

+ * <li><code>dragFinished</code> is called when the drop has successfully completed (mouse up 

+ * over a valid target) or has been terminated (such as hitting the ESC key). Perform cleanup 

+ * such as removing data from the source side on a successful move operation.

+ * </ul></p>

  *

- * @param listener the listener

+ * @param listener the listener which should be notified

  *

- * @exception SWTError 

- *	<ul><li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>

- * 		<li>ERROR_WIDGET_DISPOSED  when the widget has been disposed</li>

- * 		<li>ERROR_NULL_ARGUMENT when listener is null</li></ul>

+ * @exception IllegalArgumentException <ul>

+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>

+ * </ul>

+ * @exception SWTException <ul>

+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

+ * </ul>

+ *

+ * @see DragSourceListener

+ * @see #removeDragListener

+ * @see DragSourceEvent

  */
 public void addDragListener(DragSourceListener listener) {

 	if (listener == null) DND.error (SWT.ERROR_NULL_ARGUMENT);

@@ -182,15 +222,22 @@ public Transfer[] getTransfer(){
 

 

 

-/**	 

- * Removes the listener.

+/**

+ * Removes the listener from the collection of listeners who will

+ * be notified when a drag and drop operation is in progress.

  *

- * @param listener the listener

+ * @param listener the listener which should be notified

  *

- * @exception SWTError

- *	<ul><li>ERROR_THREAD_INVALID_ACCESS	when called from the wrong thread</li>

- * 		<li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>

- * 		<li>ERROR_NULL_ARGUMENT when listener is null</li></ul>

+ * @exception IllegalArgumentException <ul>

+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>

+ * </ul>

+ * @exception SWTException <ul>

+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

+ * </ul>

+ *

+ * @see DragSourceListener

+ * @see #addDragListener

  */
 public void removeDragListener(DragSourceListener listener) {

 	if (listener == null) DND.error (SWT.ERROR_NULL_ARGUMENT);

@@ -202,6 +249,9 @@ public void removeDragListener(DragSourceListener listener) {
  * Specifies the list of data types that can be transferred by this DragSource.

  * The application must be able to provide data to match each of these types when

  * a successful drop has occurred.

+ * 

+ * @param transferAgents a list of Transfer objects which define the types of data that can be

+ * dragged from this source

  */
 public void setTransfer(Transfer[] transferAgents){

 	this.transferAgents = transferAgents;

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
index b951650410..8caa2eebe8 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
@@ -59,9 +59,9 @@ import org.eclipse.swt.internal.photon.*;
  * </pre></code>

  *

  * <dl>

- *	<dt><b>Styles</b> <dd>DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK 

- *	<dt><b>Events</b> <dd>DND.DragEnter, DND.DragLeave, DND.DragOver, DND.DragOperationChanged, 

- *                        DND.Drop, DND.DropAccept

+ *	<dt><b>Styles</b></dt> <dd>DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK</dd>

+ *	<dt><b>Events</b></dt> <dd>DND.DragEnter, DND.DragLeave, DND.DragOver, DND.DragOperationChanged, 

+ *                             DND.DropAccept, DND.Drop </dd>

  * </dl>

  */

 public class DropTarget extends Widget {

@@ -83,13 +83,18 @@ public class DropTarget extends Widget {
 	private DragUnderEffect effect;

 	

 /**

- * Creates a new <code>DropTarget</code> to handle dropping on the specified <code>Control</code>.

+ * Creates a new <code>DropTarget</code> to allow data to be dropped on the specified 

+ * <code>Control</code>.

+ * Creating an instance of a DropTarget may cause system resources to be allocated 

+ * depending on the platform.  It is therefore mandatory that the DropTarget instance 

+ * be disposed when no longer required.

  * 

- * @param control the <code>Control</code> over which the user positions the cursor to drop data

- *

+ * @param control the <code>Control</code> over which the user positions the cursor to drop the data

  * @param style the bitwise OR'ing of allowed operations; this may be a combination of any of 

- *					DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK

+ *		   DND.DROP_NONE, DND.DROP_COPY, DND.DROP_MOVE, DND.DROP_LINK

  *

+ * @see DropTarget#dispose

+ * @see DropTarget#checkSubclass

  * @see DND#DROP_NONE

  * @see DND#DROP_COPY

  * @see DND#DROP_MOVE

@@ -124,15 +129,37 @@ public DropTarget(Control control, int style) {
 		effect = new NoDragUnderEffect(control);

 	}

 }

-/**	 

- * Adds the listener to receive events.

+/**

+ * Adds the listener to the collection of listeners who will

+ * be notified when a drag and drop operation is in progress, by sending

+ * it one of the messages defined in the <code>DropTargetListener</code>

+ * interface.

+ * 

+ * <p><ul>

+ * <li><code>dragEnter</code> is called when the cursor has entered the drop target boundaries

+ * <li><code>dragLeave</code> is called when the cursor has left the drop target boundaries and just before

+ * the drop occurs or is cancelled.

+ * <li><code>dragOperationChanged</code> is called when the operation being performed has changed 

+ * (usually due to the user changing the selected modifier key(s) while dragging)

+ * <li><code>dragOver</code> is called when the cursor is moving over the drop target

+ * <li><code>dropAccept</code> is called just before the drop is performed.  The drop target is given 

+ * the chance to change the nature of the drop or veto the drop by setting the <code>event.detail</code> field

+ * <li><code>drop</code> is called when the data is being dropped

+ * </ul></p>

  *

- * @param listener the listener

+ * @param listener the listener which should be notified

  *

- * @exception SWTError 

- *	<ul><li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>

- * 		<li>ERROR_WIDGET_DISPOSED  when the widget has been disposed</li>

- * 		<li>ERROR_NULL_ARGUMENT when listener is null</li></ul>

+ * @exception IllegalArgumentException <ul>

+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>

+ * </ul>

+ * @exception SWTException <ul>

+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

+ * </ul>

+ *

+ * @see DropTargetListener

+ * @see #removeDropListener

+ * @see DropTargetEvent

  */
 public void addDropListener(DropTargetListener listener) {	

 	if (listener == null) DND.error (SWT.ERROR_NULL_ARGUMENT);

@@ -166,9 +193,9 @@ public Display getDisplay () {
 	return control.getDisplay ();

 }

 /**

- * Returns the list of data types that can be transferred to this DropTarget.

+ * Returns a list of the data types that can be transferred to this DropTarget.

  *

- * @return the list of data types that can be transferred to this DropTarget

+ * @return a list of the data types that can be transferred to this DropTarget

  */

 public Transfer[] getTransfer(){

 	return transferAgents;

@@ -185,15 +212,22 @@ public void notifyListeners (int eventType, Event event) {
 	super.notifyListeners(eventType, event);

 }

 

-/**	 

- * Removes the listener.

+/**

+ * Removes the listener from the collection of listeners who will

+ * be notified when a drag and drop operation is in progress.

+ *

+ * @param listener the listener which should be notified

  *

- * @param listener the listener

+ * @exception IllegalArgumentException <ul>

+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>

+ * </ul>

+ * @exception SWTException <ul>

+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>

+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>

+ * </ul>

  *

- * @exception SWTError

- *	<ul><li>ERROR_THREAD_INVALID_ACCESS	when called from the wrong thread</li>

- * 		<li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>

- * 		<li>ERROR_NULL_ARGUMENT when listener is null</li></ul>

+ * @see DropTargetListener

+ * @see #addDropListener

  */
 public void removeDropListener(DropTargetListener listener) {	

 	if (listener == null) DND.error (SWT.ERROR_NULL_ARGUMENT);

@@ -205,7 +239,10 @@ public void removeDropListener(DropTargetListener listener) {
 	removeListener (DND.DropAccept, listener);

 }

 /**

- * Specifies the list of data types that can be transferred to this DropTarget.

+ * Specifies the data types that can be transferred to this DropTarget.  If data is 

+ * being dragged that does not match one of these types, the drop target will be notified of 

+ * the drag and drop operation but the currentDataType will be null and the operation 

+ * will be DND.NONE.

  *

  * @param transferAgents a list of Transfer objects which define the types of data that can be

  *						 dropped on this target

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/FileTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/FileTransfer.java
index c061af1cad..39e2304621 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/FileTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/FileTransfer.java
@@ -12,7 +12,20 @@ import org.eclipse.swt.internal.Converter;
  * The class <code>FileTransfer</code> provides a platform specific mechanism 

  * for converting a list of files represented as a java <code>String[]</code> to a 

  * platform specific representation of the data and vice versa.  

+ * Each <code>String</code> in the array contains the absolute path for a single 

+ * file or directory.

  * See <code>Transfer</code> for additional information.

+ * 

+ * <p>An example of a java <code>String[]</code> containing a list of files is shown 

+ * below:</p>

+ * 

+ * <code><pre>

+ *     File file1 = new File("C:\temp\file1");

+ *     File file2 = new File("C:\temp\file2");

+ *     String[] fileData = new String[2];

+ *     fileData[0] = file1.getAbsolutePath();

+ *     fileData[1] = file2.getAbsolutePath();

+ * </code></pre>

  */
 public class FileTransfer extends ByteArrayTransfer {

 	

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/RTFTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/RTFTransfer.java
index 28b8c767a9..b80c5d0e01 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/RTFTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/RTFTransfer.java
@@ -16,10 +16,11 @@ import org.eclipse.swt.internal.photon.OS;
  * to a platform specific representation of the data and vice versa.  See 

  * <code>Transfer</code> for additional information.

  * 

- * <p>An example of a java <code>String</code> containg RTF text is shown 

+ * <p>An example of a java <code>String</code> containing RTF text is shown 

  * below:</p>

+ * 

  * <code><pre>

- * String rtfData = "{\\rtf1{\\colortbl;\\red255\\green0\\blue0;}\\uc1\\b\\i Hello World}";

+ *     String rtfData = "{\\rtf1{\\colortbl;\\red255\\green0\\blue0;}\\uc1\\b\\i Hello World}";

  * </code></pre>

  */
 public class RTFTransfer extends ByteArrayTransfer {

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
index 4955ed8374..45d75e6323 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
@@ -15,6 +15,13 @@ import org.eclipse.swt.internal.photon.OS;
  * for converting plain text represented as a java <code>String</code> 

  * to a platform specific representation of the data and vice versa.  See 

  * <code>Transfer</code> for additional information.

+ * 

+ * <p>An example of a java <code>String</code> containing plain text is shown 

+ * below:</p>

+ * 

+ * <code><pre>

+ *     String textData = "Hello World";

+ * </code></pre>

  */
 public class TextTransfer extends ByteArrayTransfer {