ICU-2103 API docs, @stable, @draft, etc. added.

X-SVN-Rev: 10476

icu4c/source/common/unicode/brkiter.h

@@ -198,6 +198,10 @@ typedef const void* URegistryKey;
  */
 class U_COMMON_API BreakIterator : public UObject {
 public:
+    /**
+     *  destructor
+     *  @stable
+     */
     virtual ~BreakIterator();
 
     /**
@@ -564,8 +568,11 @@ public:
     friend class ICUBreakIteratorService;
 
 protected:
+    /** @internal */
     BreakIterator();
+    /** @internal */
     UBool fBufferClone;
+    /** @internal */
     BreakIterator (const BreakIterator &other) : UObject(other), fBufferClone(FALSE) {}
 private:
     /**

icu4c/source/common/unicode/dbbi.h

@@ -30,6 +30,17 @@ class DictionaryBasedBreakIteratorTables;
  * repeatedly compared against a list of known words (i.e., the dictionary)
  * to divide them up into words.
  *
+ * <p>Applications do not normally need to include this header.</p>
+ *
+ * <p>This class will probably be deprecated in a future release of ICU, and replaced
+ *  with a more flexible and capable dictionary based break iterator.  This change
+ *  should be invisible to applications, because creation and use of instances of
+ *  DictionaryBasedBreakIterator is through the factories and abstract
+ *  API on class BreakIterator, which will remain stable.</p>
+ *
+ * <p>This class is not intended to be subclassed.</p>
+ *
+ *
  * DictionaryBasedBreakIterator uses the same rule language as RuleBasedBreakIterator,
  * but adds one more special substitution name: &lt;dictionary&gt;.  This substitution
  * name is used to identify characters in words in the dictionary.  The idea is that
@@ -100,6 +111,7 @@ public:
 
     /**
      * Destructor
+     * @stable
      */
     virtual ~DictionaryBasedBreakIterator();
 
@@ -107,6 +119,7 @@ public:
      * Default constructor.  Creates an "empty" break iterator.
      * Such an iterator can subsequently be assigned to.
      * @return the newly created DictionaryBaseBreakIterator.
+     * @stable
      */
      DictionaryBasedBreakIterator();
 
@@ -114,6 +127,7 @@ public:
       * Copy constructor.
       * @param other The DictionaryBasedBreakIterator to be copied.
       * @return the newly created DictionaryBasedBreakIterator.
+      * @stable
       */
      DictionaryBasedBreakIterator(const DictionaryBasedBreakIterator &other);
 
@@ -121,6 +135,7 @@ public:
      * Assignment operator. 
      * @param that The object to be copied.
      * @return the newly set DictionaryBasedBreakIterator.
+     * @stable
      */
     DictionaryBasedBreakIterator& operator=(const DictionaryBasedBreakIterator& that);
 
@@ -128,6 +143,7 @@ public:
      * Returns a newly-constructed RuleBasedBreakIterator with the same
      * behavior, and iterating over the same text, as this one.
      * @return Returns a newly-constructed RuleBasedBreakIterator.
+     * @stable
      */
     virtual BreakIterator* clone(void) const;
 
@@ -137,6 +153,7 @@ public:
     /**
      * Advances the iterator backwards, to the last boundary preceding this one.
      * @return The position of the last boundary position preceding this one.
+     * @stable
      */
     virtual int32_t previous(void);
 
@@ -145,6 +162,7 @@ public:
      * the specified position.
      * @offset The position from which to begin searching for a break position.
      * @return The position of the first break after the current position.
+     * @stable
      */
     virtual int32_t following(int32_t offset);
 
@@ -153,6 +171,7 @@ public:
      * specified position.
      * @offset The position to begin searching for a break from.
      * @return The position of the last boundary before the starting position.
+     * @stable
      */
     virtual int32_t preceding(int32_t offset);
 
@@ -165,6 +184,7 @@ public:
      * @return          The class ID for this object. All objects of a
      *                  given class have the same class ID.  Objects of
      *                  other classes have different class IDs.
+     * @stable
      */
     virtual UClassID getDynamicClassID(void) const;
 
@@ -177,6 +197,7 @@ public:
      *          Derived::getStaticClassID()) ...
      *
      * @return          The class ID for all objects of this class.
+     * @stable
      */
     static UClassID getStaticClassID(void);
 
@@ -190,18 +211,21 @@ protected:
      * and advances through the text character by character until we reach the end
      * of the text or the state machine transitions to state 0.  We update our return
      * value every time the state machine passes through a possible end state.
+     * @internal
      */
     virtual int32_t handleNext(void);
 
     /**
      * removes the cache of break positions (usually in response to a change in
      * position of some sort)
+     * @internal
      */
     virtual void reset(void);
 
-    //
-    //  init    Initialize a dbbi.  Common routine for use by constructors.
-    //
+    /**
+     *  init    Initialize a dbbi.  Common routine for use by constructors.
+     *  @internal
+     */
     void init();
 
     /**
@@ -216,6 +240,7 @@ protected:
      *  An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any allocations were 
      *  necessary.
      * @return pointer to the new clone
+     * @internal
      */
     virtual BreakIterator *  createBufferClone(void *stackBuffer,
                                                int32_t &BufferSize,

icu4c/source/common/unicode/rbbi.h

@@ -36,31 +36,43 @@ class  RBBIDataWrapper;
 /**
  * <p>A subclass of BreakIterator whose behavior is specified using a list of rules.</p>
  * <p>Instances of this class are most commonly created by the factory methods of
- *  BreakIterator::createWordInstance(), BreakIterator::createLineInstance(), etc. </p>
+ *  BreakIterator::createWordInstance(), BreakIterator::createLineInstance(), etc.,
+ *  and then used via the abstract API in class BreakIterator</p>
+ *
  * <p>See the ICU User Guide for information on Break Iterator Rules.</p>
  *
+ * <p>This class is not intended to be subclassed.  (Class DictionaryBasedBreakIterator
+ *    is a subclass, but that relationship is effectively internal to the ICU 
+ *    implementation.  The subclassing interface to RulesBasedBreakIterator is
+ *    not part of the ICU API, and may not remain stable.</p>
+ *
  */
 class U_COMMON_API RuleBasedBreakIterator : public BreakIterator {
 
 protected:
     /**
      * The character iterator through which this BreakIterator accesses the text
+     * @internal
      */
     CharacterIterator*  fText;
 
     /**
      * The rule data for this BreakIterator instance
+     * @internal
      */
     RBBIDataWrapper    *fData;
     UTrie              *fCharMappings;
 
-    /** Rule {tag} value for the most recent match. */
+    /** Rule {tag} value for the most recent match. 
+     *  @internal
+    */
     int32_t             fLastBreakTag;
 
     /**
      * Rule tag value valid flag.
      * Some iterator operations don't intrinsically set the correct tag value.
      * This flag lets us lazily compute the value if we are ever asked for it.
+     * @internal
      */
     UBool               fLastBreakTagValid;
 
@@ -69,12 +81,14 @@ protected:
      *   flag set.  Normal RBBI iterators don't use it, although the code
      *   for updating it is live.  Dictionary Based break iterators (a subclass
      *   of us) access this field directly.
+     * @internal
      */
     uint32_t           fDictionaryCharCount;
 
-    //
-    // Debugging flag.  Trace operation of state machine when true.
-    //
+    /**
+     * Debugging flag.  Trace operation of state machine when true.
+     * @internal
+     */
     static UBool        fTrace;
 
 
@@ -94,6 +108,7 @@ protected:
      * This constructor uses the udata interface to create a BreakIterator
      * whose internal tables live in a memory-mapped file.  "image" is a pointer
      * to the beginning of that file.
+     * @internal
      */
     RuleBasedBreakIterator(UDataMemory* image, UErrorCode &status);
 
@@ -105,6 +120,7 @@ protected:
      *
      *             The break iterator adopts the memory, and will
      *             free it when done.
+     * @internal
      */
     RuleBasedBreakIterator(RBBIDataHeader* data, UErrorCode &status);
 
@@ -125,6 +141,7 @@ public:
      * Copy constructor.  Will produce a break iterator with the same behavior,
      * and which iterates over the same text, as the one passed in.
      * @param that The RuleBasedBreakIterator passed to be copied
+     * @stable
      */
     RuleBasedBreakIterator(const RuleBasedBreakIterator& that);
 
@@ -328,6 +345,7 @@ public:
      * @return          The class ID for this object. All objects of a
      *                  given class have the same class ID.  Objects of
      *                  other classes have different class IDs.
+     * @stable
      */
     inline virtual UClassID getDynamicClassID(void) const;
 
@@ -340,6 +358,7 @@ public:
      *          Derived::getStaticClassID()) ...
      *
      * @return          The class ID for all objects of this class.
+     * @stable
      */
     inline static UClassID getStaticClassID(void);
 
@@ -402,6 +421,7 @@ protected:
      * and advances through the text character by character until we reach the end
      * of the text or the state machine transitions to state 0.  We update our return
      * value every time the state machine passes through a possible end state.
+     * @internal
      */
     virtual int32_t handleNext(void);
 
@@ -411,6 +431,7 @@ protected:
      * The various calling methods then iterate forward from this safe position to
      * the appropriate position to return.  (For more information, see the description
      * of buildBackwardsStateTable() in RuleBasedBreakIterator.Builder.)
+     * @internal
      */
     virtual int32_t handlePrevious(void);
 
@@ -418,6 +439,7 @@ protected:
      * Dumps caches and performs other actions associated with a complete change
      * in text or iteration position.  This function is a no-op in RuleBasedBreakIterator,
      * but subclasses can and do override it.
+     * @internal
      */
     virtual void reset(void);
 
@@ -427,12 +449,14 @@ protected:
       * This function is intended for use by dictionary based break iterators.
       * @return true if the category lookup for this char
       * indicates that it is in the set of dictionary lookup chars.
+      * @internal
       */
     virtual UBool isDictionaryChar(UChar32);
 
     /**
       * Common initialization function, used by constructors and bufferClone.
       *   (Also used by DictionaryBasedBreakIterator::createBufferClone().)
+      * @internal
       */
     void init();
 

icu4c/source/i18n/unicode/regex.h

@@ -274,9 +274,10 @@ public:
     
     
     
-    //
-    //   dump   Debug function, displays the compiled form of a pattern.
-    //
+    /**
+     *   dump   Debug function, displays the compiled form of a pattern.
+     *   @internal
+     */
     void dump() const;
 
     /**