Bug 183164 - [Implementation for] Display of Complex Expressionsv20111108-1700v20111108-1400

Containing Bidirectional Text

15 files changed, 210 insertions, 137 deletions

diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
index 0d6a2e9e2..c8c23a1ea 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
@@ -14,8 +14,11 @@ import org.eclipse.equinox.bidi.advanced.*;
 import org.eclipse.equinox.bidi.custom.STextTypeHandler;
 
 /**
- *  Provides a number of convenience functions facilitating the
- *  processing of structured text.
+ *  Provides methods to process structured text. The methods in this class
+ *  are the most straightforward way to transform <i>lean</i> text into 
+ *  <i>full</i> text and vice versa (for the meaning of <i>lean</i> and 
+ *  <i>full</i> text, please see the 
+ *  <a href="package-summary.html">package documentation</a>).
  *
  *  @noextend This class is not intended to be subclassed by clients.
  *  @noinstantiate This class is not intended to be instantiated by clients.
@@ -50,9 +53,9 @@ public final class STextProcessor {
 	}
 
 	/**
-	 *  Processes the given text and returns a string with appropriate
-	 *  directional formatting characters. This is equivalent to calling
-	 *  {@link #process(String str, String separators)} with the default
+	 *  Processes the given (<i>lean</i>) text and returns a string with appropriate
+	 *  directional formatting characters (<i>full</i> text). This is equivalent to 
+	 *  calling {@link #process(String str, String separators)} with the default
 	 *  set of separators.
 	 *  <p>
 	 *  The processing adds directional formatting characters so that presentation 
@@ -66,9 +69,11 @@ public final class STextProcessor {
 	 *  <tt>d:\myfolder\REDLOF\ELIFYM.java</tt>.
 	 *  </p>
 	 *  
-	 *  @param  str the text to be processed.
+	 * @param  str the <i>lean</i> text to process.
 	 *  
-	 *  @return the processed string.
+	 * @return the processed string (<i>full</i> text).
+	 * 
+	 * @see #deprocess(String)
 	 */
 	public static String process(String str) {
 		return process(str, defaultSeparators);
@@ -77,13 +82,14 @@ public final class STextProcessor {
 	/**
 	 * Processes a string that has a particular semantic meaning to render
 	 * it correctly on bidi locales.
-	 *  
-	 * @see #process(String)
+	 * For more details, see {@link #process(String)}.
 	 * 
-	 * @param  str the text to process.
+	 * @param  str the <i>lean</i> text to process.
 	 * @param  separators characters by which the string will be segmented.
 	 * 
-	 * @return the processed string.
+	 * @return the processed string (<i>full</i> text).
+	 * 
+	 * @see #deprocess(String)
 	 */
 	public static String process(String str, String separators) {
 		if ((str == null) || (str.length() <= 1))
@@ -131,17 +137,18 @@ public final class STextProcessor {
 	/**
 	 * Processes a string that has a particular semantic meaning to render
 	 * it correctly on bidi locales.
+	 * For more details, see {@link #process(String)}.
 	 * 
-	 * @see #process(String)
-	 * 
-	 * @param  str the text to process.
-	 * @param  textType an identifier for the  handler instance appropriate 
-	 *         for the type of the structured text.
+	 * @param  str the <i>lean</i> text to process.
+	 * @param  textType an identifier for the structured text handler  
+	 *         appropriate for the type of the text submitted.
 	 *         It may be one of the identifiers defined in 
 	 *         {@link STextTypeHandlerFactory} or a type handler identifier 
-	 *         specified in a plug-in.
+	 *         registered by a plug-in.
 	 *         
-	 * @return the processed string
+	 * @return the processed string (<i>full</i> text).
+	 * 
+	 * @see #deprocessTyped
 	 */
 	public static String processTyped(String str, String textType) {
 		if ((str == null) || (str.length() <= 1))
@@ -163,9 +170,9 @@ public final class STextProcessor {
 	/**
 	 * Removes directional formatting characters in the given string.
 	 * 
-	 * @param  str string with directional characters to remove.
+	 * @param  str string with directional characters to remove (<i>full</i> text).
 	 * 
-	 * @return string without directional formatting characters.
+	 * @return string without directional formatting characters (<i>lean</i> text).
 	 */
 	public static String deprocess(String str) {
 		if ((str == null) || (str.length() <= 1))
@@ -195,15 +202,16 @@ public final class STextProcessor {
 	/**
 	 * Removes directional formatting characters in the given string.
 	 * 
-	 * @param  str string with directional characters to remove.
-	 * 
-	 * @param  textType an identifier for the  handler instance appropriate 
-	 *         for the type of the structured text.
+	 * @param  str string with directional characters to remove (<i>full</i> text).
+	 * @param  textType an identifier for the structured text handler  
+	 *         appropriate for the type of the text submitted.
 	 *         It may be one of the identifiers defined in 
 	 *         {@link STextTypeHandlerFactory} or a type handler identifier 
-	 *         specified in a plug-in.
+	 *         registered by a plug-in.
 	 *         
-	 * @return string without directional formatting characters.
+	 * @return string without directional formatting characters (<i>lean</i> text).
+	 * 
+	 * @see #processTyped(String, String)
 	 */
 	public static String deprocessTyped(String str, String textType) {
 		if ((str == null) || (str.length() <= 1))
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
index d134e557a..4f4513a15 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
@@ -10,12 +10,28 @@
  ******************************************************************************/
 package org.eclipse.equinox.bidi;
 
+import org.eclipse.equinox.bidi.advanced.STextEnvironment;
+import org.eclipse.equinox.bidi.advanced.STextExpertFactory;
 import org.eclipse.equinox.bidi.custom.STextTypeHandler;
 import org.eclipse.equinox.bidi.internal.STextTypesCollector;
 
 /**
  * Provides access to registered structured text handlers.
- * 
+ * <p>
+ * A structured text handler is a subclass of {@link STextTypeHandler}
+ * adapted for a given type of structured text.
+ * <p>
+ * The constants in this class are identifiers for structured text
+ * handlers which are defined and supported "out of the box" by this package.
+ * Text handler identifiers can be used when invoking {@link STextProcessor#processTyped(String, String)},
+ * or when invoking <code>getExpert</code> methods in {@link STextExpertFactory}.
+ * <p>
+ * The {@link #getHandler} method in this class can be used to get a 
+ * structured text handler reference for one of the handlers defined in this
+ * package or for additional structured text handlers registered by plug-ins.
+ * Text handler references can be used when invoking 
+ * {@link STextExpertFactory#getStatefulExpert(STextTypeHandler, STextEnvironment)}.
+ *  
  * @noinstantiate This class is not intended to be instantiated by clients.
  */
 final public class STextTypeHandlerFactory {
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
index 171a2e6f5..9cea28ff0 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
@@ -105,6 +105,7 @@ public interface ISTextExpert {
 	/**
 	 * Obtains the structured type handler associated with this 
 	 * <code>ISTextExpert</code> instance.
+	 * 
 	 * @return the type handler instance.
 	 */
 	public STextTypeHandler getTypeHandler();
@@ -214,8 +215,18 @@ public interface ISTextExpert {
 	 * </p><p> 
 	 * If necessary, leading and trailing directional formatting characters
 	 * (LRE, RLE and PDF) can be added depending on the value of the 
-	 * <code>affix</code> argument.
-	 * </p>
+	 * <code>affix</code> argument.</p>
+	 * <ul>
+	 *   <li>A value of 1 means that one LRM or RLM must be prefixed, depending  
+	 *       on the direction. This is useful when the GUI component presenting
+	 *       this text has a contextual orientation.</li>
+	 *   <li>A value of 2 means that LRE+LRM or RLE+RLM must be prefixed, 
+	 *       depending on the direction, and LRM+PDF or RLM+PDF must be
+	 *       suffixed, depending on the direction.
+	 *       This is useful if the GUI component presenting this text needs to
+	 *       have the text orientation explicitly specified.</li>
+	 *   <li>A value of 0 means that no prefix or suffix are needed.</li>
+	 * </ul>
 	 * @see ISTextExpert#leanBidiCharOffsets(String)
 	 * 
 	 * @param  text the structured text string
@@ -256,6 +267,7 @@ public interface ISTextExpert {
 	/**
 	 * Sets the state for the next text processing call.
 	 * This method does nothing if the expert instance is not a stateful one.
+	 * 
 	 * @param state an object returned by a previous call to {@link #getState}.
 	 */
 	public void setState(Object state);
@@ -263,7 +275,8 @@ public interface ISTextExpert {
 	/**
 	 * Gets the state established by the last text processing call.
 	 * This is <code>null</code> if the expert instance is not a stateful one,
-	 * or if the last text processing call has nothing to pass to the next call.
+	 * or if the last text processing call had nothing to pass to the next call.
+	 * 
 	 * @return the last established state.
 	 */
 	public Object getState();
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
index 474fb00d8..6705ddf8f 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
@@ -97,11 +97,11 @@ public class STextEnvironment {
 	/**
 	 * Creates an instance of a structured text environment.
 	 *
-	 * @param lang the language to of the environment, encoded as specified
+	 * @param lang the language of the environment, encoded as specified
 	 * in ISO-639. Might be <code>null</code>, in which case the default
 	 * locale is used.
 	 * @param mirrored specifies if the environment is mirrored.
-	 * @param orientation the orientation of the GUI component: 
+	 * @param orientation the orientation of the GUI component, one of the values: 
 	 *         {@link #ORIENT_LTR ORIENT_LTR},
 	 *         {@link #ORIENT_LTR ORIENT_RTL},
 	 *         {@link #ORIENT_CONTEXTUAL_LTR ORIENT_CONTEXTUAL_LTR},
@@ -124,6 +124,7 @@ public class STextEnvironment {
 	/**
 	 * Returns a 2-letters code representing a language as defined by
 	 * ISO-639.
+	 * 
 	 * @return language of the environment
 	 */
 	public String getLanguage() {
@@ -134,6 +135,7 @@ public class STextEnvironment {
 	 * Returns a flag indicating that structured text processed
 	 * within this environment should assume that the GUI is mirrored
 	 * (globally going from right to left).
+	 * 
 	 * @return <code>true</code> if environment is mirrored 
 	 */
 	public boolean getMirrored() {
@@ -145,7 +147,7 @@ public class STextEnvironment {
 	 * component in which the <i>full</i> structured text
 	 * will be displayed.
 	 * <p>
-	 * The orientation values:
+	 * The orientation value is one of the following:
 	 * <ul>
 	 * <li>{@link #ORIENT_LTR ORIENT_LTR},</li>
 	 * <li>{@link #ORIENT_LTR ORIENT_RTL},</li>
@@ -161,7 +163,11 @@ public class STextEnvironment {
 	}
 
 	/**
-	 * Checks if bidi processing is needed in this environment.
+	 * Checks if bidi processing is needed in this environment. The result 
+	 * depends on the operating system (must be supported by this package)
+	 * and on the language supplied when constructing the instance (it
+	 * must be a language using a bidirectional script).
+	 * 
 	 * @return <code>true</code> if bidi processing is needed in this environment.
 	 */
 	public boolean isProcessingNeeded() {
@@ -185,6 +191,12 @@ public class STextEnvironment {
 		return processingNeeded.booleanValue();
 	}
 
+	/**
+	 * Computes the hashCode based on the values supplied when constructing 
+	 * the instance and on the result of {@link #isProcessingNeeded()}.
+	 * 
+	 * @return the hash code.
+	 */
 	public int hashCode() {
 		final int prime = 31;
 		int result = 1;
@@ -195,6 +207,12 @@ public class STextEnvironment {
 		return result;
 	}
 
+	/**
+	 * Compare 2 environment instances and returns true if both instances
+	 * were constructed with the same arguments.
+	 * 
+	 * @return true if the 2 instances can be used interchangeably.
+	 */
 	public boolean equals(Object obj) {
 		if (this == obj)
 			return true;
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
index d0f7a12dd..e6e21b88a 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
@@ -19,7 +19,11 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
 
 /**
  * Obtains ISTextExpert instances.
- * There are two kinds of {@link ISTextExpert} instances (called "experts"):
+ * An {@link ISTextExpert} instance (called in short an "expert") provides
+ * the advanced methods to process a certain type of structured text, and 
+ * is thus related to a specific 
+ * {@link STextTypeHandler structured text type handler}.
+ * There are two kinds of experts:
  * <ul>
  *   <li>stateful, obtained by calling {@link #getStatefulExpert getStatefulExpert}.</li>
  *   <li>not stateful, obtained by calling {@link #getExpert getExpert}.</li>
@@ -27,6 +31,11 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
  * <p>Only the stateful kind can remember the state established by a call to
  * a text processing method and transmit it as initial state in the next call
  * to a text processing method.
+ * <p>In other words, the methods 
+ * {@link ISTextExpert#getState() getState},
+ * {@link ISTextExpert#setState setState} and
+ * {@link ISTextExpert#clearState() clearState} of 
+ * {@link ISTextExpert} are inoperative for experts which are not stateful.
  * <p>
  * Using a stateful expert is more resource intensive, thus not stateful
  * experts should be used when feasible. 
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
index 9b71e0c16..438719bbe 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
@@ -4,17 +4,11 @@
 <META name="Author" content="Matitiahu Allouche">
 </head>
 <body bgcolor="white">
-
+<p>
 This package provides classes for users  who need finer control
 on structured text handling.
-<br>
-Note that the basic functions are provided in package
-{@link <a href="../package-summary.html">
-org.eclipse.equinox.bidi</a>} and its
-{@link <a href="../STextProcessor.html">STextProcessor</a>} class.
-<p>
 In particular, the user should use the methods in the
-{@link <a href="ISTextExpert.html">ISTextExpert</a>} class
+<a href="ISTextExpert.html">ISTextExpert</a> class
 in the following cases:</p>
 <ul>
   <li>The structured type handler to use is not one of those
@@ -27,5 +21,31 @@ in the following cases:</p>
   <li>The user needs to manage the offsets where directional formatting
       characters are inserted in the text.</li>
 </ul>
+<p>
+Note that the basic functions are provided in package
+{@link <a href="../package-summary.html">
+org.eclipse.equinox.bidi</a>} and its
+{@link <a href="../STextProcessor.html">STextProcessor</a>} class.
+</p><p>
+To access the more sophisticated methods for processing structured text,
+the user should proceed as follows:</p>
+<ul>
+  <li>The user has to obtain an appropriate 
+      <code>ISTextExpert</code> instance using the methods in 
+      <a href="STextExpertFactory.html">STextExpertFactory</a>.</li>
+  <li>The user may then invoke the more sophisticated methods provided by
+      <a href="ISTextExpert.html">ISTextExpert</a> 
+      for processing the structured text.</li>
+  <li>If those methods should work in an environment different from the default,
+      the user may specify properties of the environment using the class
+      <a href="STextEnvironment.html">STextEnvironment</a>.
+      <p>
+      This should be done before obtaining a <code>ISTextExpert</code> instance, 
+      and the specific environment must be specified when invoking 
+      <code>STextExpertFactory</code> methods. This will 
+      associate a type handler with the given environment and provide
+      a customized <code>ISTextExpert</code> instance to the user.</p></li>
+</ul>
+
 </body>
 </html>
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
index f279259c4..edb87611a 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
@@ -14,7 +14,7 @@ import org.eclipse.equinox.bidi.advanced.ISTextExpert;
 import org.eclipse.equinox.bidi.advanced.STextEnvironment;
 
 /**
- * Determines bidirectional types of characters in a string.
+ * Provides services related to the bidi classification of characters.
  */
 public class STextCharTypes {
 
@@ -36,9 +36,21 @@ public class STextCharTypes {
 
 	private static final int CHARTYPES_ADD = 2;
 
+	/**
+	 * The ISTextExpert instance which created this instance.
+	 */
 	final protected ISTextExpert expert;
+	/**
+	 * The STextTypeHandler instance utilized by the expert.
+	 */
 	final protected STextTypeHandler handler;
+	/**
+	 * The environment associated with the expert.
+	 */
 	final protected STextEnvironment environment;
+	/**
+	 * The source text whose characters are analyzed.
+	 */
 	final protected String text;
 
 	// 1 byte for each char in text
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
index 086c950fa..3433de3ef 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
@@ -12,7 +12,8 @@ package org.eclipse.equinox.bidi.custom;
 
 /**
  * Provides various services related to managing the array of
- * offsets where directional formatting characters will be inserted.
+ * offsets where directional formatting characters should be inserted
+ * in a source string.
  * 
  * @author Matitiahu Allouche
  *
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
index 869b5cfb3..ad6fed49d 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
@@ -23,7 +23,9 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
  *  <ul>
  *    <li>Handler instances may be accessed simultaneously by
  *        several threads. They should have no instance variables.</li>
- *    <li>The common logic uses handler methods to query the
+ *    <li>This class provides common logic in code which can be invoked
+ *        by any {@link STextTypeHandler structured text handler}. 
+ *        This common logic uses handler methods to query the
  *        characteristics of the specific handler:
  *        <ul>
  *          <li>the separators which separate the structured text into
@@ -87,26 +89,21 @@ public class STextTypeHandler {
 	 *         is invoked. The handler can use ISTextExpert methods to
 	 *         query items stored in the expert instance, like the current
 	 *         {@link STextEnvironment environment}.      
-	 *
 	 * @param  text the structured text string before
 	 *         addition of any directional formatting characters.
-	 *
 	 * @param  charTypes an object whose methods can be useful to the 
 	 *         handler.
-	 *
 	 * @param  offsets an object whose methods can be useful to the 
 	 *         handler.
-	 *
 	 * @param  caseNumber number of the special case to locate.
 	 *         This number varies from 1 to the number of special cases
 	 *         returned by {@link #getSpecialsCount getSpecialsCount}
 	 *         for this handler.
 	 *         The meaning of this number is internal to the class
 	 *         implementing <code>indexOfSpecial</code>.
-	 *
 	 * @param  fromIndex the index within <code>text</code> to start
 	 *         the search from.
-	 *
+	 *         
 	 * @return the position where the start of the special case
 	 *         corresponding to <code>caseNumber</code> was located.
 	 *         The method must return the first occurrence of whatever
@@ -131,7 +128,7 @@ public class STextTypeHandler {
 	/**
 	 * Handles special cases specific to this handler.
 	 * It is called when a special case occurrence 
-	 * is located by {@link #indexOfSpecial}.
+	 * is located by {@link #indexOfSpecial indexOfSpecial}.
 	 * <p>
 	 * If a special processing cannot be completed within a current call to
 	 * <code>processSpecial</code> (for instance, a comment has been started
@@ -154,18 +151,13 @@ public class STextTypeHandler {
 	 *         is invoked. The handler can use ISTextExpert methods to
 	 *         query items stored in the expert instance, like the current
 	 *         {@link STextEnvironment environment}.      
-	 *
 	 * @param  text the structured text string before
 	 *         addition of any directional formatting characters.
-	 *
 	 * @param  charTypes an object whose methods can be useful to the 
 	 *         handler.
-	 *
 	 * @param  offsets an object whose methods can be useful to the 
 	 *         handler.
-	 *
 	 * @param  caseNumber number of the special case to handle.
-	 *
 	 * @param  separLocation the position returned by
 	 *         {@link #indexOfSpecial indexOfSpecial}. After calls to
 	 *         {@link ISTextExpert#leanToFullText leanToFullText} and other
@@ -195,8 +187,10 @@ public class STextTypeHandler {
 	/**
 	 * Specifies that a mark character must be added before the character
 	 * at the specified position of the <i>lean</i> text when generating the
-	 * <i>full</i> text. This method can be called from within {@link #indexOfSpecial}
-	 * or {@link #processSpecial} in extensions of <code>STextTypeHandler</code>.
+	 * <i>full</i> text. This method can be called from within 
+	 * {@link #indexOfSpecial indexOfSpecial} or
+	 * {@link #processSpecial processSpecial} in extensions of 
+	 * <code>STextTypeHandler</code>.
 	 * The mark character will be LRM for structured text
 	 * with a LTR base direction, and RLM for structured text with RTL
 	 * base direction. The mark character is not added physically by this
@@ -206,13 +200,10 @@ public class STextTypeHandler {
 	 * @param  text is the structured text string received as
 	 *         parameter to <code>indexOfSpecial</code> or
 	 *         <code>processSpecial</code>.
-	 *
 	 * @param  charTypes is a parameter received by <code>indexOfSpecial</code>
 	 *         or <code>processSpecial</code>.
-	 *
 	 * @param  offsets is a parameter received by <code>indexOfSpecial</code>
 	 *         or <code>processSpecial</code>.
-	 *
 	 * @param  offset position of the character in the <i>lean</i> text.
 	 *         It must be a non-negative number smaller than the length
 	 *         of the <i>lean</i> text.
@@ -228,8 +219,9 @@ public class STextTypeHandler {
 	 * display, depending on the base direction of the text and on the
 	 * class of the characters in the <i>lean</i> text preceding and 
 	 * following the separator itself. This method
-	 * can be called from within {@link #indexOfSpecial} or
-	 * {@link #processSpecial} in extensions of <code>STextTypeHandler</code>. 
+	 * can be called from within {@link #indexOfSpecial indexOfSpecial} or
+	 * {@link #processSpecial processSpecial} in extensions of 
+	 * <code>STextTypeHandler</code>. 
 	 * <p>
 	 * The logic implemented in this method considers the text before
 	 * <code>separLocation</code> and the text following it. If, and only if,
@@ -240,13 +232,10 @@ public class STextTypeHandler {
 	 * @param  text is the structured text string received as
 	 *         parameter to <code>indexOfSpecial</code> or
 	 *         <code>processSpecial</code>.
-	 *
 	 * @param  charTypes is a parameter received by <code>indexOfSpecial</code>
 	 *         or <code>processSpecial</code>.
-	 *
 	 * @param  offsets is a parameter received by <code>indexOfSpecial</code>
 	 *         or <code>processSpecial</code>.
-	 *
 	 * @param  separLocation offset of the separator in the <i>lean</i> text.
 	 *         It must be a non-negative number smaller than the length
 	 *         of the <i>lean</i> text.
@@ -283,7 +272,6 @@ public class STextTypeHandler {
 	 *         is invoked. The handler can use ISTextExpert methods to
 	 *         query items stored in the expert instance, like the current
 	 *         {@link STextEnvironment environment}.      
-	 *
 	 * @param  text the structured text string to process.
 	 *
 	 * @return the base direction of the structured text. This direction
@@ -308,9 +296,7 @@ public class STextTypeHandler {
 	 *         is invoked. The handler can use ISTextExpert methods to
 	 *         query items stored in the expert instance, like the current
 	 *         {@link STextEnvironment environment}.      
-	 *
 	 * @param  text is the structured text string to process.
-	 *
 	 * @param  charTypes is a parameter received by <code>indexOfSpecial</code>
 	 *         or <code>processSpecial</code>.
 	 *
@@ -364,9 +350,7 @@ public class STextTypeHandler {
 	 *         is invoked. The handler can use ISTextExpert methods to
 	 *         query items stored in the expert instance, like the current
 	 *         {@link STextEnvironment environment}.      
-	 *
 	 * @param  text is the structured text string to process.
-	 *
 	 * @param  charTypes is a parameter received by <code>indexOfSpecial</code>
 	 *         or <code>processSpecial</code>.
 	 *
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html
index 5f7ead094..6b7ac75f3 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html
@@ -5,11 +5,9 @@
 </head>
 <body bgcolor="white">
 <p>
-This package provides classes for
-developing structured text type handlers.
-</p><p>
-This package is to be used together with package
-{@link <a href="..\package-summary.html">
-org.eclipse.equinox.bidi</a>}.
+This package provides classes for developing structured text type handlers.
+It is to be used together with package 
+{@link <a href="..\package-summary.html">org.eclipse.equinox.bidi</a>}.
+</p>
 </body>
 </html>
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
index d71fcdd0a..ba6419ff6 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
@@ -50,7 +50,7 @@ public abstract class STextDelims extends STextTypeHandler {
 
 	/**
 	 *  Handles the text between start and end delimiters as a token.
-	 *  This methoed inserts a directional mark if needed at position
+	 *  This method inserts a directional mark if needed at position
 	 *  <code>separLocation</code> which corresponds to a start delimiter,
 	 *  and skips until after the matching end delimiter.
 	 *
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
index 4285ba689..d26f41901 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
@@ -10,8 +10,7 @@
  ******************************************************************************/
 package org.eclipse.equinox.bidi.internal;
 
-import org.eclipse.equinox.bidi.advanced.ISTextExpert;
-import org.eclipse.equinox.bidi.advanced.STextEnvironment;
+import org.eclipse.equinox.bidi.advanced.*;
 import org.eclipse.equinox.bidi.custom.*;
 
 /**
@@ -52,11 +51,30 @@ public class STextImpl implements ISTextExpert {
 	static final int FIXES_LENGTH = PREFIX_LENGTH + SUFFIX_LENGTH;
 	static final int[] EMPTY_INT_ARRAY = new int[0];
 
+	/**
+	 * The structured text handler utilized by this expert.
+	 */
 	protected final STextTypeHandler handler;
+	/**
+	 * The environment associated with the expert.
+	 */
 	protected final STextEnvironment environment;
+	/**
+	 * Flag which is true if the expert is stateful.
+	 */
 	protected final boolean sharedExpert;
+	/**
+	 * Last state value set by {@link #setState} or {@link #clearState}.
+	 */
 	protected Object state;
 
+	/**
+	 * Constructor used in {@link STextExpertFactory}.
+	 * 
+	 * @param structuredTextHandler the structured text handler used by this expert.
+	 * @param environment the environment associated with this expert.
+	 * @param shared flag which is true if the expert is stateful.
+	 */
 	public STextImpl(STextTypeHandler structuredTextHandler, STextEnvironment environment, boolean shared) {
 		this.handler = structuredTextHandler;
 		this.environment = environment;
@@ -127,6 +145,9 @@ public class STextImpl implements ISTextExpert {
 		return nextLocation + (((long) idxLocation) << 32);
 	}
 
+	/**
+	 * @see STextTypeHandler#processSeparator STextTypeHandler.processSeparator
+	 */
 	static public void processSeparator(String text, STextCharTypes charTypes, STextOffsets offsets, int separLocation) {
 		int len = text.length();
 		int direction = charTypes.getDirection();
@@ -226,7 +247,6 @@ public class STextImpl implements ISTextExpert {
 	 *  {@link ISTextExpert#leanToFullText leanToFullText} does not add any directional
 	 *  formatting characters as either prefix or suffix of the <i>full</i> text.
 	 *  <p>
-	 *  @see ISTextExpert#leanToFullText STextEngine.leanToFullText
 	 */
 	public String leanToFullText(String text) {
 		int len = text.length();
@@ -512,8 +532,9 @@ public class STextImpl implements ISTextExpert {
 			} else {
 				// When the orientation is RTL, we need to add EMBED at the
 				// start of the text and PDF at its end.
-				// However, because of a bug in Windows' handling of LRE/PDF,
-				// we add EMBED_PREFIX at the start and EMBED_SUFFIX at the end.
+				// However, because of a bug in Windows' handling of LRE/RLE/PDF,
+				// we add LRM or RLM (according to the direction) after the 
+				// LRE/RLE and again before the PDF.
 				char curEmbed = EMBEDS[direction];
 				fullChars[0] = curEmbed;
 				fullChars[1] = curMark;
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java
index 0c604894c..df62726d4 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextStringRecord.java
@@ -10,9 +10,8 @@
  ******************************************************************************/
 package org.eclipse.equinox.bidi.internal;
 
-import org.eclipse.equinox.bidi.STextTypeHandlerFactory;
-
 import java.lang.ref.SoftReference;
+import org.eclipse.equinox.bidi.STextTypeHandlerFactory;
 
 /**
  * Records strings which contain structured text. Several static
@@ -80,19 +79,15 @@ public class STextStringRecord {
 	 * and ending offsets for the first segment.
 	 *
 	 * @param  string the string to record.
-	 *
 	 * @param  segmentCount number of segments allowed in this string.
 	 *         This number must be >= 1.
-	 *
 	 * @param  handlerID identifier for the handler appropriate to handle 
 	 *         the type of structured text present in the first segment.
 	 *         It may be one of the predefined identifiers in 
 	 *         {@link STextTypeHandlerFactory}, or it may be an identifier
 	 *         for a type handler created by a plug-in or by the application.
-	 *
 	 * @param  start offset in the string of the starting character of the first
 	 *         segment. It must be >= 0 and less than the length of the string.
-	 *
 	 * @param  limit offset of the character following the first segment. It
 	 *         must be greater than the <code>start</code> argument and
 	 *         not greater than the length of the string.
@@ -147,10 +142,8 @@ public class STextStringRecord {
 	 *         It may be one of the predefined identifiers in 
 	 *         {@link STextTypeHandlerFactory}, or it may be an identifier
 	 *         for a type handler created by a plug-in or by the application.
-	 *
 	 * @param  start offset in the string of the starting character of the
 	 *         segment. It must be >= 0 and less than the length of the string.
-	 *
 	 * @param  limit offset of the character following the segment. It must be
 	 *         greater than the <code>start</code> argument and not greater
 	 *         than the length of the string.
@@ -179,7 +172,7 @@ public class STextStringRecord {
 	}
 
 	/**
-	 * Checks if a string is recorded and retrieve its record.
+	 * Checks if a string is recorded and retrieves its record.
 	 *
 	 * @param  string the string to check.
 	 *
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
index 4b94cace8..6daa9af0f 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
@@ -36,10 +36,16 @@ public class STextTypesCollector implements IRegistryEventListener {
 		registry.addListener(this, EXT_POINT);
 	}
 
+	/**
+	 * @return a static instance.
+	 */
 	static public STextTypesCollector getInstance() {
 		return instance;
 	}
 
+	/**
+	 * @return a list of all the registered structured text handler types.
+	 */
 	public String[] getTypes() {
 		if (types == null)
 			read();
@@ -49,6 +55,11 @@ public class STextTypesCollector implements IRegistryEventListener {
 		return result;
 	}
 
+	/**
+	 * @param type the identifier for a structured text handler.
+	 * 
+	 * @return the structured text handler instance.
+	 */
 	public STextTypeHandler getHandler(String type) {
 		if (types == null)
 			read();
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
index 665718d9c..1b23975bc 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
@@ -20,7 +20,8 @@ Bidirectional text offers interesting challenges to presentation systems.
 For plain text, the Unicode Bidirectional Algorithm
 (<a href="http://www.unicode.org/reports/tr9/">UBA</a>)
 generally specifies satisfactorily how to reorder bidirectional text for
-display. This algorithm is implemented in Java's presentation system.
+display. This algorithm is implemented in many presentation and operating 
+systems, like Java/Swing, Windows, Linux.
 </p><p>
 However, all bidirectional text is not necessarily plain text. There
 are also instances of text structured to follow a given syntax, which
@@ -72,17 +73,6 @@ For each of these types, an identifier is defined in
 These identifiers can be used as argument in some methods of
 <b>STextProcessor</b> to specify the type of handler to apply.
 </p><p>
-Another class in this package may be used to
-complement the action of
-{@link <a href="STextProcessor.html">STextProcessor</a>}:
-<ul>
-  <li>{@link <a href="STextStringRecord.html">STextStringRecord</a>}
-      allows to record strings which are structured text with the
-      type of the appropriate handler,
-      so that another module can check if a given string has been recorded
-      as a structured text string and run its type handler.</li>
-</ul>
-<p>
 The classes included in this package are intended for users who
 need to process structured text in the most straightforward
 manner, when the following conditions are satisfied:
@@ -102,51 +92,30 @@ manner, when the following conditions are satisfied:
 When their needs go beyond the conditions above,
 users can use classes in the
 {@link <a href="advanced/package-summary.html">
-org.eclipse.equinox.bidi.advanced</a>} package:
-<ul>
-  <li>{@link <a href="advanced/ISTextExpert.html">ISTextExpert</a>}
-      provides more sophisticated methods for processing the
-      structured text.</li>
-  <li>{@link <a href="advanced/STextEnvironment.html">STextEnvironment</a>}
-      specifies properties of the environment.</li>
-  <li>{@link <a href="advanced/STextExpertFactory.html">STextExpertFactory</a>}
-      associates a type handler with an environment and provides
-      a <code>STextExpert</code> instance for the user.
-</ul>
-<p>
+org.eclipse.equinox.bidi.advanced</a>} package.
+</p><p>
 Developers who want to develop new handlers to support types of
-structured text not currently supported can use the following components
+structured text not currently supported can use components
 of the package {@link <a href="custom/package-summary.html">
-org.eclipse.equinox.bidi.custom</a>}:
-<ul>
-  <li>{@link <a href="custom/STextTypeHandler.html">STextTypeHandler</a>}
-      is a generic handler to be used as superclass for specific
-      handlers.</li>
-  <li>{@link <a href="custom/STextCharTypes.html">STextCharTypes</a>}
-      provides services related to the bidi classification of characters.</li>
-  <li>{@link <a href="custom/STextOffsets.html">STextOffsets</a>}
-      provides services related to managing an array of offsets to locations
-      where directional formatting characters should be added in the source
-      string.</li>
-</ul>
-<p>
-There are two other packages associated with the current one:
+org.eclipse.equinox.bidi.custom</a>}.
+</p><p>
+There are two other packages associated with the current one:</p>
 <ul>
   <li>{@link <a href="internal/package-summary.html">
       org.eclipse.equinox.bidi.internal</a>}</li>
   <li>{@link <a href="internal/consumable/package-summary.html">
        org.eclipse.equinox.bidi.internal.consumable</a>}</li>
 </ul>
+<p>
 The tools in the first package can serve as example of how to develop
 processors for currently unsupported types of structured text.<br>
 The latter package contains classes for the processors implementing
 the currently supported types of structured text.
-<p>
+</p><p>
 However, users wishing to process the currently supported types of
 structured text typically don't need to interact with these
 two packages.
-
-<p>&nbsp;</p>
+</p>
 
 <h2>Abbreviations used in the documentation of this package</h2>
 
@@ -188,7 +157,7 @@ attention:</p>
 Linux) are very similar but nevertheless have known differences. Those
 differences are minor and will not have a visible effect in most cases.
 However there might be cases in which the same bidi text on two
-platforms might look different. These differences will surface in Java
+platforms will look different. These differences will surface in Java
 applications when they use the platform visual components for their UI
 (e.g., AWT, SWT).</li>