Skip to content

Commit be4e50c

Browse files
aheningersffc
authored andcommitted
ICU-13810 Merge pull request unicode-org#29 from aheninger/ICU-13810-SQ
ICU-13810 Doxygen warning cleanup.
2 parents 77a1c43 + 35ce529 commit be4e50c

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+2601
-379
lines changed

icu4c/source/Doxyfile.in

Lines changed: 2312 additions & 66 deletions
Large diffs are not rendered by default.

icu4c/source/common/unicode/char16ptr.h

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ U_NAMESPACE_BEGIN
2828
// Use the predefined value.
2929
#elif (defined(__clang__) || defined(__GNUC__)) && U_PLATFORM != U_PF_BROWSER_NATIVE_CLIENT
3030
# define U_ALIASING_BARRIER(ptr) asm volatile("" : : "rm"(ptr) : "memory")
31+
#elif defined(U_IN_DOXYGEN)
32+
# define U_ALIASING_BARRIER(ptr)
3133
#endif
3234

3335
/**
@@ -103,6 +105,7 @@ class U_COMMON_API Char16Ptr U_FINAL {
103105
#endif
104106
};
105107

108+
/// \cond
106109
#ifdef U_ALIASING_BARRIER
107110

108111
Char16Ptr::Char16Ptr(char16_t *p) : p_(p) {}
@@ -134,6 +137,7 @@ Char16Ptr::~Char16Ptr() {}
134137
char16_t *Char16Ptr::get() const { return u_.cp; }
135138

136139
#endif
140+
/// \endcond
137141

138142
/**
139143
* const char16_t * wrapper with implicit conversion from distinct but bit-compatible pointer types.
@@ -209,6 +213,7 @@ class U_COMMON_API ConstChar16Ptr U_FINAL {
209213
#endif
210214
};
211215

216+
/// \cond
212217
#ifdef U_ALIASING_BARRIER
213218

214219
ConstChar16Ptr::ConstChar16Ptr(const char16_t *p) : p_(p) {}
@@ -240,6 +245,7 @@ ConstChar16Ptr::~ConstChar16Ptr() {}
240245
const char16_t *ConstChar16Ptr::get() const { return u_.cp; }
241246

242247
#endif
248+
/// \endcond
243249

244250
/**
245251
* Converts from const char16_t * to const UChar *.

icu4c/source/common/unicode/docmain.h

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -208,9 +208,9 @@
208208
* <td>C API</td>
209209
* </tr>
210210
* <tr>
211-
* <td>Layout Engine/Complex Text Layout</td>
212-
* <td>loengine.h</td>
213-
* <td>icu::LayoutEngine,icu::ParagraphLayout</td>
211+
* <td>Paragraph Layout / Complex Text Layout</td>
212+
* <td>playout.h</td>
213+
* <td>icu::ParagraphLayout</td>
214214
* </tr>
215215
* <tr>
216216
* <td>ICU I/O</td>

icu4c/source/common/unicode/edits.h

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ class UnicodeString;
2424
* in linear progression. Does not support moving/reordering of text.
2525
*
2626
* There are two types of edits: <em>change edits</em> and <em>no-change edits</em>. Add edits to
27-
* instances of this class using {@link #addReplace(int, int)} (for change edits) and
28-
* {@link #addUnchanged(int)} (for no-change edits). Change edits are retained with full granularity,
27+
* instances of this class using {@link #addReplace(int32_t, int32_t)} (for change edits) and
28+
* {@link #addUnchanged(int32_t)} (for no-change edits). Change edits are retained with full granularity,
2929
* whereas adjacent no-change edits are always merged together. In no-change edits, there is a one-to-one
3030
* mapping between code points in the source and destination strings.
3131
*
@@ -62,11 +62,11 @@ class UnicodeString;
6262
* </ul>
6363
*
6464
* The "fine changes" and "coarse changes" iterators will step through only the change edits when their
65-
* {@link Edits::Iterator#next()} methods are called. They are identical to the non-change iterators when
66-
* their {@link Edits::Iterator#findSourceIndex(int)} or {@link Edits::Iterator#findDestinationIndex(int)}
65+
* `Edits::Iterator::next()` methods are called. They are identical to the non-change iterators when
66+
* their `Edits::Iterator::findSourceIndex()` or `Edits::Iterator::findDestinationIndex()`
6767
* methods are used to walk through the string.
6868
*
69-
* For examples of how to use this class, see the test <code>TestCaseMapEditsIteratorDocs</code> in
69+
* For examples of how to use this class, see the test `TestCaseMapEditsIteratorDocs` in
7070
* UCharacterCaseTest.java.
7171
*
7272
* An Edits object tracks a separate UErrorCode, but ICU string transformation functions
@@ -189,9 +189,9 @@ class U_COMMON_API Edits U_FINAL : public UMemory {
189189
* starts at {@link #sourceIndex()} and runs for {@link #oldLength()} chars; the destination string
190190
* span starts at {@link #destinationIndex()} and runs for {@link #newLength()} chars.
191191
*
192-
* The iterator can be moved between edits using the {@link #next()}, {@link #findSourceIndex(int)},
193-
* and {@link #findDestinationIndex(int)} methods. Calling any of these methods mutates the iterator
194-
* to make it point to the corresponding edit.
192+
* The iterator can be moved between edits using the `next()`, `findSourceIndex(int32_t, UErrorCode &)`,
193+
* and `findDestinationIndex(int32_t, UErrorCode &)` methods.
194+
* Calling any of these methods mutates the iterator to make it point to the corresponding edit.
195195
*
196196
* For more information, see the documentation for {@link Edits}.
197197
*
@@ -366,13 +366,13 @@ class U_COMMON_API Edits U_FINAL : public UMemory {
366366
/**
367367
* The start index of the current span in the replacement string; the span has length
368368
* {@link #newLength}. Well-defined only if the current edit is a change edit.
369-
* <p>
370-
* The <em>replacement string</em> is the concatenation of all substrings of the destination
369+
*
370+
* The *replacement string* is the concatenation of all substrings of the destination
371371
* string corresponding to change edits.
372-
* <p>
372+
*
373373
* This method is intended to be used together with operations that write only replacement
374-
* characters (e.g., {@link CaseMap#omitUnchangedText()}). The source string can then be modified
375-
* in-place.
374+
* characters (e.g. operations specifying the \ref U_OMIT_UNCHANGED_TEXT option).
375+
* The source string can then be modified in-place.
376376
*
377377
* @return the current index into the replacement-characters-only string,
378378
* not counting unchanged spans

icu4c/source/common/unicode/enumset.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ U_NAMESPACE_BEGIN
2828
* enum bitset for boolean fields. Similar to Java EnumSet<>.
2929
* Needs to range check. Used for private instance variables.
3030
* @internal
31+
* \cond
3132
*/
3233
template<typename T, uint32_t minValue, uint32_t limitValue>
3334
class EnumSet {
@@ -60,6 +61,8 @@ class EnumSet {
6061
uint32_t fBools;
6162
};
6263

64+
/** \endcond */
65+
6366
U_NAMESPACE_END
6467

6568
#endif /* U_SHOW_CPLUSPLUS_API */

icu4c/source/common/unicode/filteredbrk.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ class U_COMMON_API FilteredBreakIteratorBuilder : public UObject {
9595
* This function does not create any new segment boundaries, but only serves to un-do
9696
* the effect of earlier calls to suppressBreakAfter, or to un-do the effect of
9797
* locale data which may be suppressing certain strings.
98-
* @param exception the exception to remove
98+
* @param string the exception to remove
9999
* @param status error code
100100
* @return returns TRUE if the string was present and now removed,
101101
* FALSE if the call was a no-op because the string was not being suppressed.

icu4c/source/common/unicode/icuplug.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@
110110
#include "unicode/utypes.h"
111111

112112

113-
#if UCONFIG_ENABLE_PLUGINS
113+
#if UCONFIG_ENABLE_PLUGINS || defined(U_IN_DOXYGEN)
114114

115115

116116

icu4c/source/common/unicode/listformatter.h

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,10 @@ class Hashtable;
3333
struct ListFormatInternal;
3434

3535
/* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */
36-
/** @internal */
36+
/**
37+
* @internal
38+
* \cond
39+
*/
3740
struct ListFormatData : public UMemory {
3841
UnicodeString twoPattern;
3942
UnicodeString startPattern;
@@ -43,6 +46,7 @@ struct ListFormatData : public UMemory {
4346
ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) :
4447
twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {}
4548
};
49+
/** \endcond */
4650

4751

4852
/**

icu4c/source/common/unicode/platform.h

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@
3838
* and/or from other macros that are predefined by the compiler
3939
* or defined in standard (POSIX or platform or compiler) headers.
4040
*
41-
* As a temporary workaround, you can add an explicit <code>#define</code> for some macros
41+
* As a temporary workaround, you can add an explicit \#define for some macros
4242
* before it is first tested, or add an equivalent -D macro definition
4343
* to the compiler's command line.
4444
*
@@ -207,6 +207,9 @@
207207
# define CYGWINMSVC
208208
#endif
209209
*/
210+
#ifdef U_IN_DOXYGEN
211+
# define CYGWINMSVC
212+
#endif
210213

211214
/**
212215
* \def U_PLATFORM_USES_ONLY_WIN32_API
@@ -493,13 +496,8 @@ namespace std {
493496
*/
494497
#ifdef U_NOEXCEPT
495498
/* Use the predefined value. */
496-
#elif defined(_HAS_EXCEPTIONS) && !_HAS_EXCEPTIONS /* Visual Studio */
497-
# define U_NOEXCEPT
498-
#elif U_CPLUSPLUS_VERSION >= 11 || __has_feature(cxx_noexcept) || __has_extension(cxx_noexcept) \
499-
|| (defined(_MSC_VER) && _MSC_VER >= 1900) /* Visual Studio 2015 */
500-
# define U_NOEXCEPT noexcept
501499
#else
502-
# define U_NOEXCEPT
500+
# define U_NOEXCEPT noexcept
503501
#endif
504502

505503
/**
@@ -763,7 +761,8 @@ namespace std {
763761
#elif U_HAVE_CHAR16_T \
764762
|| (defined(__xlC__) && defined(__IBM_UTF_LITERAL) && U_SIZEOF_WCHAR_T != 2) \
765763
|| (defined(__HP_aCC) && __HP_aCC >= 035000) \
766-
|| (defined(__HP_cc) && __HP_cc >= 111106)
764+
|| (defined(__HP_cc) && __HP_cc >= 111106) \
765+
|| (defined(U_IN_DOXYGEN))
767766
# define U_DECLARE_UTF16(string) u ## string
768767
#elif U_SIZEOF_WCHAR_T == 2 \
769768
&& (U_CHARSET_FAMILY == 0 || (U_PF_OS390 <= U_PLATFORM && U_PLATFORM <= U_PF_OS400 && defined(__UCS2__)))

icu4c/source/common/unicode/ptypes.h

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ typedef unsigned char uint8_t;
8383

8484
#else /* neither U_HAVE_STDINT_H nor U_HAVE_INTTYPES_H */
8585

86+
/// \cond
8687
#if ! U_HAVE_INT8_T
8788
typedef signed char int8_t;
8889
#endif
@@ -122,6 +123,7 @@ typedef unsigned int uint32_t;
122123
typedef unsigned long long uint64_t;
123124
#endif
124125
#endif
126+
/// \endcond
125127

126128
#endif /* U_HAVE_STDINT_H / U_HAVE_INTTYPES_H */
127129

icu4c/source/common/unicode/stringtriebuilder.h

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,10 @@
2626
*/
2727

2828
// Forward declaration.
29+
/// \cond
2930
struct UHashtable;
3031
typedef struct UHashtable UHashtable;
32+
/// \endcond
3133

3234
/**
3335
* Build options for BytesTrieBuilder and CharsTrieBuilder.
@@ -188,7 +190,10 @@ class U_COMMON_API StringTrieBuilder : public UObject {
188190

189191
// Do not conditionalize the following with #ifndef U_HIDE_INTERNAL_API,
190192
// it is needed for layout of other objects.
191-
/** @internal */
193+
/**
194+
* @internal
195+
* \cond
196+
*/
192197
class Node : public UObject {
193198
public:
194199
Node(int32_t initialHash) : hash(initialHash), offset(0) {}
@@ -391,7 +396,9 @@ class U_COMMON_API StringTrieBuilder : public UObject {
391396
int32_t length;
392397
Node *next; // A branch sub-node.
393398
};
399+
394400
#endif /* U_HIDE_INTERNAL_API */
401+
/// \endcond
395402

396403
/** @internal */
397404
virtual Node *createLinearMatchNode(int32_t i, int32_t unitIndex, int32_t length,

icu4c/source/common/unicode/ubiditransform.h

Lines changed: 29 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -26,33 +26,38 @@
2626
/**
2727
* \file
2828
* \brief Bidi Transformations
29+
*/
30+
31+
/**
32+
* `UBiDiOrder` indicates the order of text.
2933
*
30-
* <code>UBiDiOrder</code> indicates the order of text.<p>
3134
* This bidi transformation engine supports all possible combinations (4 in
3235
* total) of input and output text order:
33-
* <ul>
34-
* <li><logical input, visual output>: unless the output direction is RTL, this
35-
* corresponds to a normal operation of the Bidi algorithm as described in the
36-
* Unicode Technical Report and implemented by <code>UBiDi</code> when the
37-
* reordering mode is set to <code>UBIDI_REORDER_DEFAULT</code>. Visual RTL
38-
* mode is not supported by <code>UBiDi</code> and is accomplished through
39-
* reversing a visual LTR string,</li>
40-
* <li><visual input, logical output>: unless the input direction is RTL, this
41-
* corresponds to an "inverse bidi algorithm" in <code>UBiDi</code> with the
42-
* reordering mode set to <code>UBIDI_REORDER_INVERSE_LIKE_DIRECT</code>.
43-
* Visual RTL mode is not not supported by <code>UBiDi</code> and is
44-
* accomplished through reversing a visual LTR string,</li>
45-
* <li><logical input, logical output>: if the input and output base directions
46-
* mismatch, this corresponds to the <code>UBiDi</code> implementation with the
47-
* reordering mode set to <code>UBIDI_REORDER_RUNS_ONLY</code>; and if the
48-
* input and output base directions are identical, the transformation engine
49-
* will only handle character mirroring and Arabic shaping operations without
50-
* reordering,</li>
51-
* <li><visual input, visual output>: this reordering mode is not supported by
52-
* the <code>UBiDi</code> engine; it implies character mirroring, Arabic
53-
* shaping, and - if the input/output base directions mismatch - string
54-
* reverse operations.</li>
55-
* </ul>
36+
*
37+
* - <logical input, visual output>: unless the output direction is RTL, this
38+
* corresponds to a normal operation of the Bidi algorithm as described in the
39+
* Unicode Technical Report and implemented by `UBiDi` when the
40+
* reordering mode is set to `UBIDI_REORDER_DEFAULT`. Visual RTL
41+
* mode is not supported by `UBiDi` and is accomplished through
42+
* reversing a visual LTR string,
43+
*
44+
* - <visual input, logical output>: unless the input direction is RTL, this
45+
* corresponds to an "inverse bidi algorithm" in `UBiDi` with the
46+
* reordering mode set to `UBIDI_REORDER_INVERSE_LIKE_DIRECT`.
47+
* Visual RTL mode is not not supported by `UBiDi` and is
48+
* accomplished through reversing a visual LTR string,
49+
*
50+
* - <logical input, logical output>: if the input and output base directions
51+
* mismatch, this corresponds to the `UBiDi` implementation with the
52+
* reordering mode set to `UBIDI_REORDER_RUNS_ONLY`; and if the
53+
* input and output base directions are identical, the transformation engine
54+
* will only handle character mirroring and Arabic shaping operations without
55+
* reordering,
56+
*
57+
* - <visual input, visual output>: this reordering mode is not supported by
58+
* the `UBiDi` engine; it implies character mirroring, Arabic
59+
* shaping, and - if the input/output base directions mismatch - string
60+
* reverse operations.
5661
* @see ubidi_setInverse
5762
* @see ubidi_setReorderingMode
5863
* @see UBIDI_REORDER_DEFAULT

icu4c/source/common/unicode/uconfig.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@
183183
*/
184184
#ifdef U_HAVE_LIB_SUFFIX
185185
/* Use the predefined value. */
186-
#elif defined(U_LIB_SUFFIX_C_NAME)
186+
#elif defined(U_LIB_SUFFIX_C_NAME) || defined(U_IN_DOXYGEN)
187187
# define U_HAVE_LIB_SUFFIX 1
188188
#endif
189189

icu4c/source/common/unicode/ucurr.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ enum UCurrencyUsage {
6060
UCURR_USAGE_COUNT=2
6161
#endif // U_HIDE_DEPRECATED_API
6262
};
63+
/** Currency Usage used for Decimal Format */
6364
typedef enum UCurrencyUsage UCurrencyUsage;
6465

6566
/**

icu4c/source/common/unicode/umachine.h

Lines changed: 6 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,9 @@
125125
* May result in an error if it applied to something not an override.
126126
* @internal
127127
*/
128+
#ifndef U_OVERRIDE
129+
#define U_OVERRIDE override
130+
#endif
128131

129132
/**
130133
* \def U_FINAL
@@ -133,24 +136,10 @@
133136
* May result in an error if subclasses attempt to override.
134137
* @internal
135138
*/
136-
137-
#if U_CPLUSPLUS_VERSION >= 11
138-
/* C++11 */
139-
#ifndef U_OVERRIDE
140-
#define U_OVERRIDE override
141-
#endif
142-
#ifndef U_FINAL
139+
#if !defined(U_FINAL) || defined(U_IN_DOXYGEN)
143140
#define U_FINAL final
144141
#endif
145-
#else
146-
/* not C++11 - define to nothing */
147-
#ifndef U_OVERRIDE
148-
#define U_OVERRIDE
149-
#endif
150-
#ifndef U_FINAL
151-
#define U_FINAL
152-
#endif
153-
#endif
142+
154143

155144
/*==========================================================================*/
156145
/* limits for int32_t etc., like in POSIX inttypes.h */
@@ -318,7 +307,7 @@ typedef int8_t UBool;
318307
* UChar is configurable by defining the macro UCHAR_TYPE
319308
* on the preprocessor or compiler command line:
320309
* -DUCHAR_TYPE=uint16_t or -DUCHAR_TYPE=wchar_t (if U_SIZEOF_WCHAR_T==2) etc.
321-
* (The UCHAR_TYPE can also be #defined earlier in this file, for outside the ICU library code.)
310+
* (The UCHAR_TYPE can also be \#defined earlier in this file, for outside the ICU library code.)
322311
* This is for transitional use from application code that uses uint16_t or wchar_t for UTF-16.
323312
*
324313
* The default is UChar=char16_t.

0 commit comments

Comments
 (0)