--- a/dwt/widgets/IME.d	Tue Jul 01 08:58:50 2008 +0200
+++ b/dwt/widgets/IME.d	Tue Jul 01 10:15:59 2008 +0200
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007 IBM Corporation and others.
+ * Copyright (c) 2007, 2008 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -12,6 +12,7 @@
 
 
 import dwt.DWT;
+import dwt.DWTException;
 import dwt.graphics.Color;
 import dwt.graphics.TextStyle;
 import dwt.internal.win32.OS;
@@ -25,21 +26,25 @@
 import dwt.dwthelper.utils;
 
 /**
- * TODO - JAVA DOC
+ * Instances of this class represent input method editors.
+ * These are typically in-line pre-edit text areas that allow
+ * the user to compose characters from Far Eastern languages
+ * such as Japanese, Chinese or Korean.
  *
  * <dl>
  * <dt><b>Styles:</b></dt>
  * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
- * <dd>(none)</dd>
+ * <dd>ImeComposition</dd>
  * </dl>
  * <p>
- * .
+ * IMPORTANT: This class is <em>not</em> intended to be subclassed.
  * </p>
  *
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
+ * 
  * @since 3.4
  */
-
 public class IME : Widget {
     Canvas parent;
     int caretOffset;
@@ -76,8 +81,31 @@
 }
 
 /**
+ * Constructs a new instance of this class given its parent
+ * and a style value describing its behavior and appearance.
+ * <p>
+ * The style value is either one of the style constants defined in
+ * class <code>DWT</code> which is applicable to instances of this
+ * class, or must be built by <em>bitwise OR</em>'ing together 
+ * (that is, using the <code>int</code> "|" operator) two or more
+ * of those <code>DWT</code> style constants. The class description
+ * lists the style constants that are applicable to the class.
+ * Style bits are also inherited from superclasses.
+ * </p>
  *
- * @see DWT
+ * @param parent a canvas control which will be the parent of the new instance (cannot be null)
+ * @param style the style of control to construct
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * </ul>
+ * @exception DWTException <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 Widget#checkSubclass
+ * @see Widget#getStyle
  */
 public this (Canvas parent, int style) {
     super (parent, style);
@@ -86,23 +114,62 @@
 }
 
 void createWidget () {
-    text = "";
+    text = ""; //$NON-NLS-1$
     startOffset = -1;
     if (parent.getIME () is null) {
         parent.setIME (this);
     }
 }
 
+/**
+ * Returns the offset of the caret from the start of the document.
+ * The caret is within the current composition.
+ *
+ * @return the caret offset
+ *
+ * @exception DWTException <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>
+ */
 public int getCaretOffset () {
     checkWidget ();
     return startOffset + caretOffset;
 }
 
+/**
+ * Returns the commit count of the composition.  This is the
+ * number of characters that have been composed.  When the
+ * commit count is equal to the length of the composition
+ * text, then the in-line edit operation is complete.
+ * 
+ * @return the commit count
+ *
+ * @exception DWTException <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 IME#getText
+ */
 public int getCommitCount () {
     checkWidget ();
     return commitCount;
 }
 
+/**
+ * Returns the offset of the composition from the start of the document.
+ * This is the start offset of the composition within the document and
+ * in not changed by the input method editor itself during the in-line edit
+ * session.
+ *
+ * @return the offset of the composition
+ *
+ * @exception DWTException <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>
+ */
 public int getCompositionOffset () {
     checkWidget ();
     return startOffset;
@@ -165,6 +232,24 @@
     return pda;
 }
 
+/**
+ * Returns the ranges for the style that should be applied during the
+ * in-line edit session.
+ * <p>
+ * The ranges array contains start and end pairs.  Each pair refers to
+ * the corresponding style in the styles array.  For example, the pair
+ * that starts at ranges[n] and ends at ranges[n+1] uses the style
+ * at styles[n/2] returned by <code>getStyles()</code>.
+ * </p>
+ * @return the ranges for the styles
+ *
+ * @exception DWTException <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 IME#getStyles
+ */
 public int [] getRanges () {
     checkWidget ();
     if (ranges is null) return new int [0];
@@ -175,6 +260,24 @@
     return result;
 }
 
+/**
+ * Returns the styles for the ranges.
+ * <p>
+ * The ranges array contains start and end pairs.  Each pair refers to
+ * the corresponding style in the styles array.  For example, the pair
+ * that starts at ranges[n] and ends at ranges[n+1] uses the style
+ * at styles[n/2].
+ * </p>
+ * 
+ * @return the ranges for the styles
+ *
+ * @exception DWTException <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 IME#getRanges
+ */
 public TextStyle [] getStyles () {
     checkWidget ();
     if (styles is null) return new TextStyle [0];
@@ -183,11 +286,40 @@
     return result;
 }
 
+/**
+ * Returns the composition text.
+ * <p>
+ * The text for an IME is the characters in the widget that
+ * are in the current composition. When the commit count is
+ * equal to the length of the composition text, then the
+ * in-line edit operation is complete.
+ * </p>
+ *
+ * @return the widget text
+ *
+ * @exception DWTException <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>
+ */
 public String getText () {
     checkWidget ();
     return text;
 }
 
+/**
+ * Returns <code>true</code> if the caret should be wide, and
+ * <code>false</code> otherwise.  In some languages, for example
+ * Korean, the caret is typically widened to the width of the
+ * current character in the in-line edit session.
+ * 
+ * @return the wide caret state
+ *
+ * @exception DWTException <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>
+ */
 public bool getWideCaret() {
     checkWidget ();
     auto layout = OS.GetKeyboardLayout (0);
@@ -213,6 +345,22 @@
     ranges = null;
 }
 
+/**
+ * Sets the offset of the composition from the start of the document.
+ * This is the start offset of the composition within the document and
+ * in not changed by the input method editor itself during the in-line edit
+ * session but may need to be changed by clients of the IME.  For example,
+ * if during an in-line edit operation, a text editor inserts characters
+ * above the IME, then the IME must be informed that the composition
+ * offset has changed.
+ *
+ * @return the offset of the composition
+ *
+ * @exception DWTException <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>
+ */
 public void setCompositionOffset (int offset) {
     checkWidget ();
     if (offset < 0) return;
@@ -250,7 +398,7 @@
                 commitCount = text.length ;
                 sendEvent (DWT.ImeComposition, event);
                 String chars = text;
-                text = "";
+                text = ""; //$NON-NLS-1$
                 startOffset = -1;
                 commitCount = 0;
                 if (event.doit) {