diff --git src/org/eclipse/equinox/bidi/STextProcessor.java src/org/eclipse/equinox/bidi/STextProcessor.java index fcfe7f5..b57a33d 100644 --- src/org/eclipse/equinox/bidi/STextProcessor.java +++ src/org/eclipse/equinox/bidi/STextProcessor.java @@ -14,7 +14,7 @@ import org.eclipse.equinox.bidi.custom.STextTypeHandler; /** - * This class provides a number of convenience functions facilitating the + * Provides a number of convenience functions facilitating the * processing of structured text. * * @noextend This class is not intended to be subclassed by clients. @@ -25,7 +25,8 @@ public final class STextProcessor { /** - * The default set of separators used to segment a string: dot, colon, slash, backslash. + * The default set of separators used to segment a string: dot, + * colon, slash, backslash. */ private static final String defaultSeparators = ".:/\\"; //$NON-NLS-1$ @@ -49,7 +50,7 @@ } /** - * Process the given text and return a string with appropriate + * 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 * set of separators. @@ -64,20 +65,25 @@ * (where capital letters indicate RTL text) should render as * d:\myfolder\REDLOF\ELIFYM.java. *

- * @param str the text to be processed - * @return the processed string + * + * @param str the text to be processed. + * + * @return the processed string. */ public static String process(String str) { return process(str, defaultSeparators); } /** - * Process a string that has a particular semantic meaning to render - * it correctly on bidi locales. + * Processes a string that has a particular semantic meaning to render + * it correctly on bidi locales. + * * @see #process(String) - * @param str the text to process - * @param separators separators by which the string will be segmented - * @return the processed string + * + * @param str the text to process. + * @param separators characters by which the string will be segmented. + * + * @return the processed string. */ public static String process(String str, String separators) { if ((str == null) || (str.length() <= 1)) @@ -118,16 +124,23 @@ // make sure that LRE/PDF are added around the string STextTypeHandler handler = new STextTypeHandler(separators); - ISTextExpert expert = STextExpertFactory.getExpert(handler, env); + ISTextExpert expert = STextExpertFactory.getStatefulExpert(handler, env); return expert.leanToFullText(str); } /** * Processes a string that has a particular semantic meaning to render - * it correctly on bidi locales. + * it correctly on bidi locales. + * * @see #process(String) - * @param str the text to process - * @param handler a handler instance appropriate for the type of the structured text + * + * @param str the text to process. + * @param textType an identifier for the handler instance appropriate + * for the type of the structured text. + * It may be one of the identifiers defined in + * {@link STextTypeHandlerFactory} or a type handler identifier + * specified in a plug-in. + * * @return the processed string */ public static String processTyped(String str, String textType) { @@ -149,8 +162,10 @@ /** * Removes directional formatting characters in the given string. - * @param str string with directional characters to remove - * @return string without directional formatting characters + * + * @param str string with directional characters to remove. + * + * @return string without directional formatting characters. */ public static String deprocess(String str) { if ((str == null) || (str.length() <= 1)) @@ -179,9 +194,16 @@ /** * Removes directional formatting characters in the given string. - * @param str string with directional characters to remove - * @param handler appropriate for the structured text - * @return string without directional formatting characters + * + * @param str string with directional characters to remove. + * + * @param textType an identifier for the handler instance appropriate + * for the type of the structured text. + * It may be one of the identifiers defined in + * {@link STextTypeHandlerFactory} or a type handler identifier + * specified in a plug-in. + * + * @return string without directional formatting characters. */ public static String deprocessTyped(String str, String textType) { if ((str == null) || (str.length() <= 1)) @@ -196,10 +218,10 @@ } /** - * Return the string containing all the default separator characters to be + * Returns a string containing all the default separator characters to be * used to segment a given string. * - * @return string containing all separators + * @return string containing all separators. */ public static String getDefaultSeparators() { return defaultSeparators; diff --git src/org/eclipse/equinox/bidi/STextStringRecord.java src/org/eclipse/equinox/bidi/STextStringRecord.java index 60d48d8..ab22794 100644 --- src/org/eclipse/equinox/bidi/STextStringRecord.java +++ src/org/eclipse/equinox/bidi/STextStringRecord.java @@ -13,7 +13,7 @@ import java.lang.ref.SoftReference; /** - * This class records strings which contain structured text. Several static + * Records strings which contain structured text. Several static * methods in this class allow to record such strings in a pool, and to find if * a given string is member of the pool. *

@@ -73,7 +73,7 @@ } /** - * Record a string in the pool. The caller must specify the number + * Records a string in the pool. The caller must specify the number * of segments in the record (at least 1), and the handler, starting * and ending offsets for the first segment. * @@ -82,10 +82,11 @@ * @param segmentCount number of segments allowed in this string. * This number must be >= 1. * - * @param handler the handler appropriate to handle the type - * of structured text present in the first segment. - * It may be one of the pre-defined handler instances, or it may be an instance - * created by a plug-in or by the application. + * @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. @@ -95,7 +96,7 @@ * not greater than the length of the string. * * @return an instance of STextRecordString which represents this record. - * This instance may be used to specify additional segment with + * This instance may be used to specify additional segments with * {@link #addSegment addSegment}. * * @throws IllegalArgumentException if string is null or @@ -137,12 +138,13 @@ } /** - * Add a second or further segment to a record. + * Adds a second or further segment to a record. * - * @param handler the handler appropriate to handle the type - * of structured text present in this segment. - * It may be one of the pre-defined handler instances, or it may be an instance - * created by a plug-in or by the application. + * @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 * segment. It must be >= 0 and less than the length of the string. @@ -151,7 +153,7 @@ * greater than the start argument and not greater * than the length of the string. * - * @throws IllegalArgumentException if handler is null, + * @throws IllegalArgumentException if handlerID is null, * or if start or limit have invalid * values. * @throws IllegalStateException if the current segment exceeds the @@ -161,7 +163,7 @@ */ public void addSegment(String handlerID, int start, int limit) { if (handlerID == null) - throw new IllegalArgumentException("The handler argument must not be null!"); //$NON-NLS-1$ + throw new IllegalArgumentException("The handlerID argument must not be null!"); //$NON-NLS-1$ if (start < 0 || start >= string.length()) throw new IllegalArgumentException("The start position must be at least 0 and less than the length of the string!"); //$NON-NLS-1$ if (limit <= start || limit > string.length()) @@ -175,16 +177,16 @@ } /** - * Check if a string is recorded and retrieve its record. + * Checks if a string is recorded and retrieve its record. * * @param string the string to check. * * @return null if the string is not recorded in the pool; - * otherwise, return the STextStringRecord instance which - * records this string.
+ * otherwise, return the STextStringRecord instance + * which records this string.
* Once a record has been found, the number of its segments can * be retrieved using {@link #getSegmentCount getSegmentCount}, - * its handler can + * its handler ID can * be retrieved using {@link #getHandler getHandler}, * its starting offset can * be retrieved using {@link #getStart getStart}, @@ -223,7 +225,8 @@ } /** - * Retrieve the number of segments in a record. + * Retrieves the number of segments in a record. + * * @return the number of segments in the current record */ public int getSegmentCount() { @@ -236,21 +239,18 @@ } /** - * Retrieve the handler of a given segment. + * Retrieves the handler ID of a given segment. * * @param segmentNumber number of the segment about which information * is required. It must be >= 0 and less than the number of - * segments specified by segmentCount - * in the call to {@link #addRecord addRecord} which created - * the STextStringRecord instance. + * segments returned by {@link #getSegmentCount}. * - * @return the handler to handle the structured text in the segment + * @return the handler ID of the handler appropriate to + * process the structured text in the segment * specified by segmentNumber. * * @throws IllegalArgumentException if segmentNumber * has an invalid value. - * - * @see #getSegmentCount */ public String getHandler(int segmentNumber) { checkSegmentNumber(segmentNumber); @@ -258,21 +258,17 @@ } /** - * Retrieve the starting offset of a given segment. + * Retrieves the starting offset of a given segment. * * @param segmentNumber number of the segment about which information * is required. It must be >= 0 and less than the number of - * segments specified by segmentCount - * in the call to {@link #addRecord addRecord} which created - * the STextStringRecord instance. + * segments returned by {@link #getSegmentCount}. * * @return the starting offset within the string of the segment * specified by segmentNumber. * * @throws IllegalArgumentException if segmentNumber * has an invalid value. - * - * @see #getSegmentCount */ public int getStart(int segmentNumber) { checkSegmentNumber(segmentNumber); @@ -280,21 +276,17 @@ } /** - * Retrieve the ending offset of a given segment. + * Retrieves the ending offset of a given segment. * * @param segmentNumber number of the segment about which information * is required. It must be >= 0 and less than the number of - * segments specified by segmentCount - * in the call to {@link #addRecord addRecord} which created - * the STextStringRecord instance. + * segments returned by {@link #getSegmentCount}. * * @return the offset of the position following the segment * specified by segmentNumber. * * @throws IllegalArgumentException if segmentNumber * has an invalid value. - * - * @see #getSegmentCount */ public int getLimit(int segmentNumber) { checkSegmentNumber(segmentNumber); @@ -302,7 +294,7 @@ } /** - * Clear the pool. All elements of the pool are erased and any associated + * Clears the pool. All elements of the pool are erased and any associated * memory is freed. */ public static synchronized void clear() { diff --git src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java index 5889e9b..9a3eba2 100644 --- src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java +++ src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java @@ -14,14 +14,14 @@ import org.eclipse.equinox.bidi.internal.STextTypesCollector; /** - * This class provides access to registered structured text handlers. + * Provides access to registered structured text handlers. * * @noinstantiate This class is not intended to be instantiated by clients. */ final public class STextTypeHandlerFactory { /** - * Structured text handler for property file statements. It expects the following format: + * Structured text handler identifier for property file statements. It expects the following format: * 

 	 *  name=value
 	 *
@@ -29,7 +29,7 @@ public static final String PROPERTY = "property"; //$NON-NLS-1$ /** - * Structured text handler for compound names. It expects text to be made of one or more + * Structured text handler identifier for compound names. It expects text to be made of one or more * parts separated by underscores: * 
 	 *  part1_part2_part3
@@ -38,7 +38,7 @@
 	public static final String UNDERSCORE = "underscore"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for comma-delimited lists, such as:
+	 * Structured text handler identifier for comma-delimited lists, such as:
 	 * 
 	 *  part1,part2,part3
 	 * 

@@ -46,7 +46,7 @@
 	public static final String COMMA_DELIMITED = "comma"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for strings with the following format:
+	 * Structured text handler identifier for strings with the following format:
 	 * 
 	 *  system(user)
 	 * 

@@ -54,42 +54,46 @@
 	public static final String SYSTEM_USER = "system"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for directory and file paths.
+	 * Structured text handler identifier for directory and file paths.
 	 */
 	public static final String FILE = "file"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for e-mail addresses.
+	 * Structured text handler identifier for e-mail addresses.
 	 */
 	public static final String EMAIL = "email"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for URLs.
+	 * Structured text handler identifier for URLs.
 	 */
 	public static final String URL = "url"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for regular expressions, possibly spanning multiple lines.
+	 * Structured text handler identifier for regular expressions, 
+	 * possibly spanning multiple lines.
 	 */
 	public static final String REGEXP = "regex"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for XPath expressions.
+	 * Structured text handler identifier for XPath expressions.
 	 */
 	public static final String XPATH = "xpath"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for Java code, possibly spanning multiple lines.
+	 * Structured text handler identifier for Java code, 
+	 * possibly spanning multiple lines.
 	 */
 	public static final String JAVA = "java"; //$NON-NLS-1$
 
 	/**
-	 * Structured text handler for SQL statements, possibly spanning multiple lines.
+	 * Structured text handler identifier for SQL statements, 
+	 * possibly spanning multiple lines.
 	 */
 	public static final String SQL = "sql"; //$NON-NLS-1$
 
 	/**
-	 *  Structured text handler for arithmetic expressions, possibly with a RTL base direction.
+	 *  Structured text handler identifier for arithmetic expressions, 
+	 *  possibly with a RTL base direction.
 	 */
 	public static final String RTL_ARITHMETIC = "math"; //$NON-NLS-1$
 
@@ -101,9 +105,12 @@
 	}
 
 	/**
-	 *  Obtain a structured text handler of a given type.
-	 *  @param id string identifying handler
-	 *  @return a handler of the required type, or null if the type is unknown
+	 *  Obtains a structured text handler of a given type.
+	 *  
+	 *  @param id the string identifying a structured text handler.
+	 *  
+	 *  @return a handler of the required type, or null 
+	 *          if the type is unknown.
 	 */
 	static public STextTypeHandler getHandler(String id) {
 		return STextTypesCollector.getInstance().getHandler(id);
diff --git src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
index 535e275..dbb5fb0 100644
--- src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
+++ src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
@@ -13,40 +13,44 @@
 import org.eclipse.equinox.bidi.custom.STextTypeHandler;
 
 /**
+ * Advanced API for processing structured text.
  * For a general introduction to structured text, see
- * {@link  the package documentation}.
+ * {@link the org.eclipse.equinox.bidi
+ * package documentation}.
  * 

- * Several common handlers are included in STextEngine. For handlers 
+ * Identifiers for several common handlers are included in 
+ * {@link org.eclipse.equinox.bidi.STextTypeHandlerFactory}. For handlers 
  * supplied by other packages, a handler instance can be obtained using the
  * {@link org.eclipse.equinox.bidi.STextTypeHandlerFactory#getHandler}
  * method for the registered handlers, or by instantiating a private handler.
  * 

- * Most of the methods in this class have a text
+ * Most of the methods in this interface have a text
  * argument which may be just a part of a larger body of text.
  * When it is the case that the text is submitted in parts with
  * repeated calls, there may be a need to pass information from
  * one invocation to the next one. For instance, one invocation
  * may detect that a comment or a literal has been started but
- * has not been completed. In such cases, a state
- * argument must be used.
+ * has not been completed. In such cases, the state must be managed
+ * by a ISTextExpert instance obtained with the 
+ * {@link STextExpertFactory#getStatefulExpert getStateful} method.
  * 

- * The state argument must be an array of integers
- * with at least one element. Only the first element is used by
- * the methods of this class.
+ * The state returned after processing a string
+ * can be retrieved, set and reset using the {@link #getState()},
+ * {@link #setState(Object)} and {@link #clearState()} methods.
  * 

- * When submitting the initial part of the text, the first element
- * of state must contain the value {@link #STATE_INITIAL}
- * or any value <= 0.
+ * When submitting the initial part of a text, the state should be
+ * reset if it is not the first processing call for this 
+ * ISTextExpert instance.
  * 

- * After calling a method with a non-null state argument,
- * a value is returned in the first element of state. This
- * value should be passed unmodified to the method when calling it again
- * with the text which is the continuation of the text submitted in the
- * last call.
+ * Values returned by {@link #getState()} are opaque objects whose meaning
+ * is internal to the relevant structured type handler. These values can only
+ * be used in {@link #setState(Object) setState} calls to restore a state
+ * previously obtained after processing a given part of a text before 
+ * processing the next part of the text.
  * 

- * When the text submitted to a method is not a continuation and is not
- * expected to have a continuation , e.g. it is processed all by itself,
- * the state argument should be specified as null.
+ * Note that if the user does not modify the state, the state returned by
+ * a given processing call is automatically passed as initial state to the
+ * next processing call, provided that the expert is a stateful one.
  * 

  * Code Samples
  * 

@@ -54,8 +58,9 @@
  * (directory and file paths) in order to obtain the full
  * text corresponding to the given lean text.
  * 
+ *   ISTextExpert expert = STextExpertFactory.getExpert(STextTypeHandlerFactory.FILE);
  *   String leanText = "D:\\\u05d0\u05d1\\\u05d2\\\u05d3.ext";
- *   String fullText = STextEngine.leanToFullText(STextEngine.PROC_FILE, null, leanText, null);
+ *   String fullText = expert.leanToFullText(leanText);
  *   System.out.println("full text = " + fullText);
  * 

  * 

@@ -63,12 +68,12 @@
  * code in order to obtain the full
  * text corresponding to the lean text of each line.
  * 
- *   Object state = STextState.createState();
+ *   ISTextExpert expert = STextExpertFactory.getStatefulExpert(STextTypeHandlerFactory.JAVA);
  *   String leanText = "int i = 3; // first Java statement";
- *   String fullText = STextEngine.leanToFullText(STextEngine.PROC_JAVA, null, leanText, state);
+ *   String fullText = expert.leanToFullText(leanText);
  *   System.out.println("full text = " + fullText);
  *   leanText = "i += 4; // next Java statement";
- *   fullText = STextEngine.leanToFullText(STextEngine.PROC_JAVA, null, leanText, state);
+ *   fullText = expert.leanToFullText(leanText,);
  *   System.out.println("full text = " + fullText);
  * 

  * 

@@ -80,10 +85,10 @@
 	/**
 	 *  Constant specifying that the base direction of a structured text is LTR.
 	 *  The base direction may depend on whether the GUI is
-	 *  {@link STextEnvironment#getMirrored mirrored} and may
+	 *  {@link STextEnvironment#getMirrored mirrored} and
 	 *  may be different for Arabic and for Hebrew.
 	 *  This constant can appear as value returned by the
-	 *  {@link #getCurDirection getCurDirection} method.
+	 *  {@link #getTextDirection getTextDirection} method.
 	 */
 	public static final int DIR_LTR = 0;
 
@@ -93,30 +98,29 @@
 	 *  {@link STextEnvironment#getMirrored mirrored} and may
 	 *  may be different for Arabic and for Hebrew.
 	 *  This constant can appear as value returned by the
-	 *  {@link #getCurDirection getCurDirection} method.
+	 *  {@link #getTextDirection getTextDirection} method.
 	 */
 	public static final int DIR_RTL = 1;
 
+	/**
+	 * Obtains the structured type handler associated with this 
+	 * ISTextExpert instance.
+	 * @return the type handler instance.
+	 */
 	public STextTypeHandler getTypeHandler();
 
+	/**
+	 * Obtains the environment associated with this 
+	 * ISTextExpert instance.
+	 * @return the environment instance.
+	 */
 	public STextEnvironment getEnvironment();
 
 	/** 
-	 * Add directional formatting characters to a structured text
+	 * Adds directional formatting characters to a structured text
 	 * to ensure correct presentation.
 	 * 
-	 * @param  handler the handler applicable to the text. If null, 
-	 * the method returns unmodified text.
-	 * 
-	 * @param  environment a bidi environment. If null, the default environment 
-	 * is used.
-	 *  
 	 * @param text is the structured text string
-	 *
-	 * @param  state can be used to specify that the text argument is 
-	 * the continuation of text submitted in a previous call and/or to receive information 
-	 * to pass to continuation calls. If all calls to this method are independent from one another,
-	 * this argument should be specified as null.
 	 *
 	 * @return the structured text with directional formatting characters added to ensure 
 	 * correct presentation.
@@ -124,29 +128,19 @@
 	public String leanToFullText(String text);
 
 	/**
-	 * Given a lean string, compute the positions of each of its
+	 * Given a lean string, computes the positions of each of its
 	 * characters within the corresponding full string.
-	 *
-	 * @param  handler designates a handler instance. If null, this 
-	 * method returns an identity map.
-	 *
-	 * @param  environment specifies an environment whose characteristics may affect 
-	 * the handler's behavior. If null, the default environment is used.
 	 *
 	 * @param text is the structured text string.
 	 *
-	 * @param  state can be used to specify that the text argument is 
-	 * the continuation of text submitted in a previous call and/or to receive information 
-	 * to pass to continuation calls. If all calls to this method are independent from one another,
-	 * this argument should be specified as null.
-	 *
-	 * @return an array which specifies offsets of the text characters
-	 * in the full string
+	 * @return an array of integers with one element for each of the
+	 * characters in the text argument, equal to the offset
+	 * of the corresponding character in the full string.
 	 */
 	public int[] leanToFullMap(String text);
 
 	/**
-	 * Given a lean string, compute the offsets of characters
+	 * Given a lean string, computes the offsets of characters
 	 * before which directional formatting characters must be added
 	 * in order to ensure correct presentation.
 	 * 

@@ -156,17 +150,7 @@
 	 * depending on the {@link STextEnvironment#getOrientation orientation} of the
 	 * GUI component used for display are not reflected in this method.
 	 * 

-	 * @param handler designates a handler instance
-	 *
-	 * @param  environment specifies an environment whose characteristics may affect 
-	 * the handler's behavior. If null, the default environment is used.
-	 *
 	 * @param text is the structured text string
-	 *
-	 * @param  state can be used to specify that the text argument is 
-	 * the continuation of text submitted in a previous call and/or to receive information 
-	 * to pass to continuation calls. If all calls to this method are independent from one another,
-	 * this argument should be specified as null.
 	 *
 	 * @return an array of offsets to the characters in the text argument 
 	 * before which directional marks must be added to ensure correct presentation.
@@ -175,20 +159,10 @@
 	public int[] leanBidiCharOffsets(String text);
 
 	/**
-	 * Remove directional formatting characters which were added to a
+	 * Removes directional formatting characters which were added to a
 	 * structured text string to ensure correct presentation.
-	 *
-	 * @param  handler designates a handler instance
-	 *
-	 * @param  environment specifies an environment whose characteristics may affect 
-	 * the handler's behavior. If null, the default environment is used.
 	 *
 	 * @param text is the structured text string including directional formatting characters.
-	 *
-	 * @param  state can be used to specify that the text argument is 
-	 * the continuation of text submitted in a previous call and/or to receive information 
-	 * to pass to continuation calls. If all calls to this method are independent from one another,
-	 * this argument should be specified as null.
 	 *
 	 * @return the structured text string without directional formatting characters 
 	 * which might have been added by processing it with {@link #leanToFullText}.
@@ -197,31 +171,23 @@
 	public String fullToLeanText(String text);
 
 	/**
-	 * Given a full string, compute the positions of each of its
+	 * Given a full string, computes the positions of each of its
 	 * characters within the corresponding lean string.
-	 *
-	 * @param  handler designates a handler instance
-	 *
-	 * @param  environment specifies an environment whose characteristics may affect 
-	 * the handler's behavior. If null, the default environment is used.
 	 *
 	 * @param  text is the structured text string including directional formatting characters.
 	 *
-	 * @param  state can be used to specify that the text argument is 
-	 * the continuation of text submitted in a previous call and/or to receive information 
-	 * to pass to continuation calls. If all calls to this method are independent from one another,
-	 * this argument should be specified as null.
-	 *
-	 * @return an array of integers with one element for each of the characters
-	 * in the text argument, equal to the offset of the corresponding character 
-	 * in the lean string. If there is no corresponding character in the lean string 
-	 * (because the specified character is a directional formatting character added when invoking 
-	 * {@link #leanToFullText}), the value returned for this character is -1.
+	 * @return an array of integers with one element for each of the
+	 * characters in the text argument, equal to the offset
+	 * of the corresponding character in the lean string.
+	 * If there is no corresponding character in the lean string 
+	 * (because the specified character is a directional formatting character
+	 * added when invoking {@link #leanToFullText}), 
+	 * the value returned for this character is -1.
 	 */
 	public int[] fullToLeanMap(String text);
 
 	/**
-	 * Given a full string, return the offsets of characters
+	 * Given a full string, returns the offsets of characters
 	 * which are directional formatting characters that have been added
 	 * in order to ensure correct presentation.
 	 * 

@@ -230,17 +196,7 @@
 	 * or suffixed depending on the {@link STextEnvironment#getOrientation orientation} 
 	 * of the GUI component used for display.
 	 * 

-	 * @param  handler designates a handler instance
-	 *
-	 * @param  environment specifies an environment whose characteristics may affect 
-	 * the handler's behavior. If null, the default environment is used.
-	 *
 	 * @param  text is the structured text string including directional formatting characters
-	 *
-	 * @param  state can be used to specify that the text argument is 
-	 * the continuation of text submitted in a previous call and/or to receive information 
-	 * to pass to continuation calls. If all calls to this method are independent from one another,
-	 * this argument should be specified as null.
 	 *
 	 * @return an array of offsets to the characters in the text argument which 
 	 * are directional formatting characters added to ensure correct presentation. The offsets 
@@ -249,15 +205,16 @@
 	public int[] fullBidiCharOffsets(String text);
 
 	/** 
-	 * This method adds directional marks to the given text before the characters 
+	 * Adds directional marks to the given text before the characters 
 	 * specified in the given array of offsets. It can be used to add a prefix and/or 
 	 * a suffix of directional formatting characters.
 	 * 

 	 * The directional marks will be LRMs for structured text strings with LTR base 
 	 * direction and RLMs for strings with RTL base direction.
 	 * 
 
-	 * If necessary, leading and trailing directional markers (LRE, RLE and PDF) can 
-	 * be added depending on the value of the affix argument.
+	 * If necessary, leading and trailing directional formatting characters
+	 * (LRE, RLE and PDF) can be added depending on the value of the 
+	 * affix argument.
 	 * 

 	 * @see ISTextExpert#leanBidiCharOffsets(String)
 	 * 
@@ -269,8 +226,12 @@
 	 * @param  direction the base direction of the structured text.
 	 *         It must be one of the values {@link #DIR_LTR}, or
 	 *         {@link #DIR_RTL}.
-	 * @param  affix specifies if a prefix and a suffix should be added to
-	 *         the result
+	 * @param  affixLength specifies the length of prefix and suffix 
+	 *         which should be added to the result.

+	 *         0 means no prefix or suffix

+	 *         1 means one LRM or RLM as prefix and no suffix

+	 *         2 means 2 characters in both prefix and suffix.
+	 *         
 	 * @return a string corresponding to the source text with
 	 *         directional marks (LRMs or RLMs) added at the specified offsets,
 	 *         and directional formatting characters (LRE, RLE, PDF) added
@@ -283,29 +244,33 @@
 	 * whether the text contains Arabic or Hebrew words. If the text contains both, 
 	 * the first Arabic or Hebrew letter in the text determines which is the governing script.
 	 *
-	 * @param  handler designates a handler instance
-	 *
-	 * @param  environment specifies an environment whose characteristics may affect 
-	 * the handler's behavior. If null, the default environment is used.
-	 *
-	 * @param  text is the structured text string
+	 * @param  text is the structured text string.
 	 *
 	 * @return the base direction of the structured text, {@link #DIR_LTR} or {@link #DIR_RTL}
 	 */
 	public int getTextDirection(String text);
 
-	///////////////////////////////////////////////////////////////////////////////////////////////
+	//////////////////////////////////////////////////////////////////////
 	// Expert's state handling - can be used only for non-shared experts
-
-	// TBD is there a case where we get a shared expert and setting state is a "must"?
-	// Javadoc note: shared experts will ignore this
+	//////////////////////////////////////////////////////////////////////
+	/**
+	 * 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);
 
-	// Javadoc note: may return null. Will return null for shared experts
+	/**
+	 * Gets the state established by the last text processing call.
+	 * This is null if the expert instance is not a stateful one,
+	 * or if the last text processing call has nothing to pass to the next call.
+	 * @return the last established state.
+	 */
 	public Object getState();
 
 	/**
-	 * Resets state to initial.
+	 * Resets the state to initial.
+	 * This method does nothing if the expert instance is not a stateful one.
 	 */
 	public void clearState();
 }
diff --git src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
index 6e21116..474fb00 100644
--- src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
+++ src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
@@ -13,8 +13,8 @@
 import org.eclipse.equinox.bidi.internal.STextActivator;
 
 /**
- *  This class describes environment within which structured text strings are 
- *  processed. It includes, for example:
+ *  Describes the environment within which structured text strings are 
+ *  processed. It includes:
  *