Bug 364417 - Integrate Bidi bundles docs into Eclipse help
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 c8c23a1..219b2b8 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.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 9cea28f..574f4fb 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 @@
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 @@
* 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 @@
* </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 @@
* {@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 @@
* {@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 421a625..7af08f0 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 @@
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 @@
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 e6e21b8..ead93f3 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 @@
* {@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 @@
* @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 @@
* @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 @@
* @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 3433de3..0cff8f8 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 @@
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 ad6fed4..0385284 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
* @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 6b7ac75..4e205c7 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 1b23975..a60f856 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 @@
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>
