Bug 364417 - Integrate Bidi bundles docs into Eclipse helpv20111215-1958

8 files changed, 71 insertions, 68 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 c8c23a1ea..219b2b874 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,10 +14,12 @@ import org.eclipse.equinox.bidi.advanced.*;
 import org.eclipse.equinox.bidi.custom.STextTypeHandler;
 
 /**
- *  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 
+ *  Provides methods to process bidirectional text with a specific 
+ *  structure. The methods in this class are the most straightforward 
+ *  way to add directional formatting characters to the source text to 
+ *  ensure correct presentation, or to remove those characters to 
+ *  restore the original text
+ *  (for more explanations, please see the 
  *  <a href="package-summary.html">package documentation</a>).
  *
  *  @noextend This class is not intended to be subclassed by clients.
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 9cea28ff0..574f4fb43 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
@@ -13,9 +13,13 @@ package org.eclipse.equinox.bidi.advanced;
 import org.eclipse.equinox.bidi.custom.STextTypeHandler;
 
 /**
- * Advanced API for processing structured text.
- * For a general introduction to structured text, see
- * {@link <a href="../package-summary.html">the org.eclipse.equinox.bidi
+ * Provides advanced methods for processing bidirectional text with 
+ * a specific structure to ensure proper presentation.
+ * For a general introduction to structured text, see the 
+ * {@link <a href="../package-summary.html">org.eclipse.equinox.bidi
+ * package documentation</a>}.
+ * For details about when the advanced methods are needed, see
+ * {@link <a href="package-summary.html">this
  * package documentation</a>}.
  * <p>
  * Identifiers for several common handlers are included in 
@@ -32,7 +36,7 @@ import org.eclipse.equinox.bidi.custom.STextTypeHandler;
  * may detect that a comment or a literal has been started but
  * has not been completed. In such cases, the state must be managed
  * by a <code>ISTextExpert</code> instance obtained with the 
- * {@link STextExpertFactory#getStatefulExpert getStateful} method.
+ * {@link STextExpertFactory#getStatefulExpert} method.
  * </p><p>
  * The <code>state</code> returned after processing a string
  * can be retrieved, set and reset using the {@link #getState()},
@@ -44,7 +48,7 @@ import org.eclipse.equinox.bidi.custom.STextTypeHandler;
  * </p><p>
  * 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
+ * be used in {@link #setState(Object)} calls to restore a state
  * previously obtained after processing a given part of a text before 
  * processing the next part of the text.
  * </p><p>
@@ -88,7 +92,7 @@ public interface ISTextExpert {
 	 *  {@link STextEnvironment#getMirrored mirrored} and
 	 *  may be different for Arabic and for Hebrew.
 	 *  This constant can appear as value returned by the
-	 *  {@link #getTextDirection getTextDirection} method.
+	 *  {@link #getTextDirection} method.
 	 */
 	public static final int DIR_LTR = 0;
 
@@ -98,7 +102,7 @@ public interface ISTextExpert {
 	 *  {@link STextEnvironment#getMirrored mirrored} and may
 	 *  may be different for Arabic and for Hebrew.
 	 *  This constant can appear as value returned by the
-	 *  {@link #getTextDirection getTextDirection} method.
+	 *  {@link #getTextDirection} method.
 	 */
 	public static final int DIR_RTL = 1;
 
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 421a625ee..7af08f0ce 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
@@ -191,7 +191,9 @@ public class STextEnvironment {
 		return processingNeeded.booleanValue();
 	}
 
-	/**
+	/*
+	 * (non-Javadoc)
+	 * 
 	 * Computes the hashCode based on the values supplied when constructing 
 	 * the instance and on the result of {@link #isProcessingNeeded()}.
 	 * 
@@ -207,7 +209,9 @@ public class STextEnvironment {
 		return result;
 	}
 
-	/**
+	/*
+	 * (non-Javadoc)
+	 * 
 	 * Compare 2 environment instances and returns true if both instances
 	 * were constructed with the same arguments.
 	 * 
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 e6e21b88a..ead93f3f5 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
@@ -25,16 +25,16 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
  * {@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>
+ *   <li>stateful, obtained by calling {@link #getStatefulExpert}.</li>
+ *   <li>not stateful, obtained by calling {@link #getExpert}.</li>
  * </ul>  
  * <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#getState()},
+ * {@link ISTextExpert#setState} and
+ * {@link ISTextExpert#clearState()} of 
  * {@link ISTextExpert} are inoperative for experts which are not stateful.
  * <p>
  * Using a stateful expert is more resource intensive, thus not stateful
@@ -113,7 +113,7 @@ final public class STextExpertFactory {
 	 * @param  environment the current environment, which may affect the behavior of
 	 *         the expert. This parameter may be specified as
 	 *         <code>null</code>, in which case the
-	 *         {@link STextEnvironment#DEFAULT DEFAULT}
+	 *         {@link STextEnvironment#DEFAULT}
 	 *         environment should be assumed.
 	 * @return the ISTextExpert instance.
 	 * @throws IllegalArgumentException if <code>type</code> is not a known type
@@ -168,7 +168,7 @@ final public class STextExpertFactory {
 	 * @param  environment the current environment, which may affect the behavior of
 	 *         the expert. This parameter may be specified as
 	 *         <code>null</code>, in which case the
-	 *         {@link STextEnvironment#DEFAULT DEFAULT}
+	 *         {@link STextEnvironment#DEFAULT}
 	 *         environment should be assumed.
 	 * @return the ISTextExpert instance.
 	 * @throws IllegalArgumentException if <code>type</code> is not a known type
@@ -192,7 +192,7 @@ final public class STextExpertFactory {
 	 * @param  environment the current environment, which may affect the behavior of
 	 *         the expert. This parameter may be specified as
 	 *         <code>null</code>, in which case the
-	 *         {@link STextEnvironment#DEFAULT DEFAULT}
+	 *         {@link STextEnvironment#DEFAULT}
 	 *         environment should be assumed.
 	 * @return the ISTextExpert instance.
 	 * @throws IllegalArgumentException if <code>type</code> is not a known type
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 3433de3ef..0cff8f845 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
@@ -36,6 +36,12 @@ public class STextOffsets {
 	private int prefixLength;
 
 	/**
+	 *  Default constructor
+	 */
+	public STextOffsets() {
+	}
+
+	/**
 	 *  @return the stored prefix length
 	 */
 	public int getPrefixLength() {
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 ad6fed49d..0385284ae 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
@@ -29,30 +29,30 @@ import org.eclipse.equinox.bidi.internal.STextImpl;
  *        characteristics of the specific handler:
  *        <ul>
  *          <li>the separators which separate the structured text into
- *              tokens. See {@link #getSeparators getSeparators}.</li>
+ *              tokens. See {@link #getSeparators}.</li>
  *          <li>the direction which governs the display of tokens
- *              one after the other. See {@link #getDirection getDirection}.</li>
+ *              one after the other. See {@link #getDirection}.</li>
  *          <li>the number of special cases which need to be handled by
  *              code specific to that handler.
- *              See {@link #getSpecialsCount getSpecialsCount}.</li>
+ *              See {@link #getSpecialsCount}.</li>
  *        </ul></li>
  *    <li>Before starting deeper analysis of the submitted text, the common
  *        logic gives to the handler a chance to shorten the process by
- *        invoking its {@link #skipProcessing skipProcessing} method.</li>
+ *        invoking its {@link #skipProcessing} method.</li>
  *    <li>The common logic then analyzes the text to segment it into tokens
  *        according to the appearance of separators (as retrieved using
- *        {@link #getSeparators getSeparators}).</li>
+ *        {@link #getSeparators}).</li>
  *    <li>If the handler indicated a positive number of special cases as
- *        return value from its {@link #getSpecialsCount getSpecialsCount}
+ *        return value from its {@link #getSpecialsCount}
  *        method, the common logic will repeatedly invoke the handler's
- *        {@link #indexOfSpecial indexOfSpecial} method to let it signal the
+ *        {@link #indexOfSpecial} method to let it signal the
  *        presence of special strings which may further delimit the source text.</li>
  *    <li>When such a special case is signaled by the handler, the common
- *        logic will call the handler's {@link #processSpecial processSpecial}
+ *        logic will call the handler's {@link #processSpecial}
  *        method to give it the opportunity to handle it as needed. Typical
  *        actions that the handler may perform are to add directional marks
- *        unconditionally (by calling {@link #insertMark insertMark} or
- *        conditionally (by calling {@link #processSeparator processSeparator}).</li>
+ *        unconditionally (by calling {@link #insertMark} or
+ *        conditionally (by calling {@link #processSeparator}).</li>
  *  </ul>
  *
  * @author Matitiahu Allouche
@@ -97,7 +97,7 @@ public class STextTypeHandler {
 	 *         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}
+	 *         returned by {@link #getSpecialsCount}
 	 *         for this handler.
 	 *         The meaning of this number is internal to the class
 	 *         implementing <code>indexOfSpecial</code>.
@@ -128,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 indexOfSpecial}.
+	 * is located by {@link #indexOfSpecial}.
 	 * <p>
 	 * If a special processing cannot be completed within a current call to
 	 * <code>processSpecial</code> (for instance, a comment has been started
@@ -159,8 +159,8 @@ public class STextTypeHandler {
 	 *         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
+	 *         {@link #indexOfSpecial}. After calls to
+	 *         {@link ISTextExpert#leanToFullText} and other
 	 *         methods of {@link ISTextExpert} which set a non-null
 	 *         final state, <code>processSpecial</code> is
 	 *         called when initializing the processing with value of
@@ -188,8 +188,8 @@ 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 indexOfSpecial} or
-	 * {@link #processSpecial processSpecial} in extensions of 
+	 * {@link #indexOfSpecial} or
+	 * {@link #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
@@ -219,8 +219,8 @@ 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 indexOfSpecial} or
-	 * {@link #processSpecial processSpecial} in extensions of 
+	 * can be called from within {@link #indexOfSpecial} or
+	 * {@link #processSpecial} in extensions of 
 	 * <code>STextTypeHandler</code>. 
 	 * <p>
 	 * The logic implemented in this method considers the text before
@@ -314,8 +314,8 @@ public class STextTypeHandler {
 	/**
 	 * Indicates the number of special cases handled by the current handler.
 	 * This method is invoked before starting the processing.
-	 * If the number returned is zero, {@link #indexOfSpecial indexOfSpecial}
-	 * and {@link #processSpecial processSpecial} will not be invoked.
+	 * If the number returned is zero, {@link #indexOfSpecial}
+	 * and {@link #processSpecial} will not be invoked.
 	 * <p>
 	 * If not overridden, this method returns <code>zero</code>.
 	 * </p>
@@ -327,8 +327,8 @@ public class STextTypeHandler {
 	 * @return the number of special cases for the associated handler.
 	 *         Special cases exist for some types of structured text
 	 *         handlers. They are implemented by overriding methods
-	 *         {@link STextTypeHandler#indexOfSpecial indexOfSpecial} and
-	 *         {@link STextTypeHandler#processSpecial processSpecial}.
+	 *         {@link STextTypeHandler#indexOfSpecial} and
+	 *         {@link STextTypeHandler#processSpecial}.
 	 *         Examples of special cases are comments, literals, or
 	 *         anything which is not identified by a one-character separator.
 	 *
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 6b7ac75f3..4e205c7fa 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,9 +5,9 @@
 </head>
 <body bgcolor="white">
 <p>
-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>}.
+This package provides APIs for plug-in developers to contribute 
+handlers for specific types of bidirectional expressions not 
+supported in the standard distribution.
 </p>
 </body>
 </html>
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 1b23975bc..a60f856a8 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
@@ -5,14 +5,12 @@
 </head>
 <body bgcolor="white">
 
-This package provides classes for
-processing structured text.
+This package provides classes for processing bidirectional 
+text with a special structure to ensure its proper presentation.
 <p>
 There are various types of structured text. Each type should
-be handled by a specific <i>type handler</i>. A number of standard
-type handlers are supplied in the associated package
-<a href="internal/consumable/package-summary.html">
-org.eclipse.equinox.bidi.internal.consumable</a>.
+be handled by a specific <i>type handler</i>. A number of 
+standard type handlers are supplied with this package.
 
 <h2>Introduction to Structured Text</h2>
 <p>
@@ -98,23 +96,12 @@ Developers who want to develop new handlers to support types of
 structured text not currently supported can use components
 of the package {@link <a href="custom/package-summary.html">
 org.eclipse.equinox.bidi.custom</a>}.
+The source code of packages org.eclipse.equinox.bidi.* can serve as example of
+how to develop processors for currently unsupported types of structured text.
 </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>
-However, users wishing to process the currently supported types of
-structured text typically don't need to interact with these
-two packages.
+However, users wishing to process the currently supported types of structured
+text typically don't need to deal with the org.eclipse.equinox.bidi.custom
+package.
 </p>
 
 <h2>Abbreviations used in the documentation of this package</h2>