From 5d7f0b8100e063683d6feb312640e503f4c5bfa4 Mon Sep 17 00:00:00 2001 From: Mihai Nita Date: Thu, 6 Feb 2025 19:15:37 +0000 Subject: [PATCH] ICU-23041 Hard-code the code citations and remove jcite --- docs/processes/release/tasks/docs.md | 3 - docs/processes/release/tasks/release-build.md | 5 - docs/userguide/dev/codingguidelines.md | 34 +--- .../com/ibm/icu/text/DateIntervalFormat.java | 94 ++++++++++- .../icu/text/DateTimePatternGenerator.java | 146 +++++++++++++++++- .../java/com/ibm/icu/text/PluralFormat.java | 75 ++++++++- .../ibm/icu/text/RuleBasedNumberFormat.java | 2 +- .../java/com/ibm/icu/util/BasicTimeZone.java | 107 ++++++++++++- icu4j/pom.xml | 25 --- icu4j/stylesheet8.css | 92 ----------- 10 files changed, 414 insertions(+), 169 deletions(-) diff --git a/docs/processes/release/tasks/docs.md b/docs/processes/release/tasks/docs.md index 289604c37b6..959667df0b1 100644 --- a/docs/processes/release/tasks/docs.md +++ b/docs/processes/release/tasks/docs.md @@ -368,9 +368,6 @@ Note: This is also referenced below [Upload API documentations](docs.md#upload-a ### ICU4J -**Note:** JCite must be installed for building ICU4J documentation: - - Build the API documentation pages for the new release: ``` diff --git a/docs/processes/release/tasks/release-build.md b/docs/processes/release/tasks/release-build.md index 5995ffa7bee..8b1358fca2a 100644 --- a/docs/processes/release/tasks/release-build.md +++ b/docs/processes/release/tasks/release-build.md @@ -36,7 +36,6 @@ compiled with Java system libraries from JRE 7.* * Java Runtime Environment 7 (used as bootclasspath for cross-compilation) * Apache Ant 1.10.x (the latest available version) \[\] -* JCite 1.13.0 \[\] ### Other Prerequisites only for GA @@ -56,9 +55,6 @@ compiled with Java system libraries from JRE 7.* ### Configuration * Set environment variable `JAVA_HOME` to point to the JDK directory. -* Set environment variable `JCITE_DIR` to specify JCite binary location (see[ - Building ICU4J API Reference Document with - JCite](../../../setup/java/ant/index.md)) * See `build.properties` to check version strings are properly set. * `api.report.version` / `api.report.prev.version` are used for locating API signature files and should be integer numbers. @@ -150,7 +146,6 @@ compiled with Java system libraries from JRE 7.* [echo] [WARNING] Insufficient Build Configuration for ICU4J Release [echo] JDK Tools Version: 1.8.0_152 [echo] JRE 7 System Library Path: Not Defined! - [echo] JCite Library Path: /home/yoshito/java-libs/jcite-1.13.0/build/jcite.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/commons-discovery-0.4.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/commons-logging-1.1.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/java2html.jar` [echo] ################################################################ BUILD SUCCESSFUL diff --git a/docs/userguide/dev/codingguidelines.md b/docs/userguide/dev/codingguidelines.md index bc22dc0e801..b572a095183 100644 --- a/docs/userguide/dev/codingguidelines.md +++ b/docs/userguide/dev/codingguidelines.md @@ -198,41 +198,9 @@ Coding examples help users to understand the usage of each API. Whenever possible, it is encouraged to embed a code snippet illustrating the usage of an API along with the functional specification. -#### Embedding Coding Examples in ICU4J - JCite - -Since ICU4J 49M2, the ICU4J ant build target "doc" utilizes an external tool -called [JCite](https://arrenbrecht.ch/jcite/). The tool allows us to cite a -fragment of existing source code into JavaDoc comment using a tag. To embed a -code snippet with the tag. For example, -`{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getNextTransitionExample}` -will be replaced a fragment of code marked by comment lines -`// ---getNextTransisionExample` in `BasicTimeZoneExample.java` in package -`com.ibm.icu.samples.util.timezone`. When embedding code snippet using JCite, we -recommend to follow next guidelines - -* A sample code should be placed in `/samples/src` directory, - although you can cite any source fragment from source files in - `/demos/src`, `/main/core/*/src`, - `/main/test/*/src`. -* A sample code should use package name - - `com.ibm.icu.samples..`. `` is corresponding - to the target ICU API class's package, that is, one of lang/math/text/util. - `` is a name of facility, which is usually the base class of the - service. For example, use package `com.ibm.icu.samples.text.dateformat` for - samples related to ICU's date format service, - `com.ibm.icu.samples.util.timezone` for samples related to time zone service. -* A sample code should be self-contained as much as possible (use only JDK and - ICU public APIs if possible). This allows readers to cut & paste a code - snippet to try it out easily. -* The citing comment should start with three consecutive hyphen followed by - lower camel case token - for example, "`// ---compareToExample`" -* Keep in mind that the JCite tag `{@.jcite ...}` is not resolved without JCite. - It is encouraged to avoid placing code snippet within a sentence. Instead, - you should place a code snippet using JCite in an independent paragraph. - #### Embedding Coding Examples in ICU4C -Also since ICU4C 49M2, ICU4C docs (using the [\\snippet command](http://www.doxygen.nl/manual/commands.html#cmdsnippet) +Since ICU4C 49M2, ICU4C docs (using the [\\snippet command](http://www.doxygen.nl/manual/commands.html#cmdsnippet) which is new in Doxygen 1.7.5) can cite a fragment of existing sample or test code. Example in `ucnv.h`: diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/text/DateIntervalFormat.java b/icu4j/main/core/src/main/java/com/ibm/icu/text/DateIntervalFormat.java index 2aadacd762e..d73fbe38e83 100644 --- a/icu4j/main/core/src/main/java/com/ibm/icu/text/DateIntervalFormat.java +++ b/icu4j/main/core/src/main/java/com/ibm/icu/text/DateIntervalFormat.java @@ -570,7 +570,54 @@ public class DateIntervalFormat extends UFormat { * This is a convenient override of * getInstance(String skeleton, ULocale locale) * - *

Example code:{@.jcite com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:---dtitvfmtPreDefinedExample} + * + *

Example code:

+ * + * 

+     * import java.util.Date;
+     *
+     * import com.ibm.icu.text.DateFormat;
+     * import com.ibm.icu.text.DateIntervalFormat;
+     * import com.ibm.icu.text.DateIntervalInfo;
+     * import com.ibm.icu.util.Calendar;
+     * import com.ibm.icu.util.DateInterval;
+     * import com.ibm.icu.util.GregorianCalendar;
+     * import com.ibm.icu.util.ULocale;
+     * ...
+     * final Date date[] = {
+     *         new GregorianCalendar(2007,10,10,10,10,10).getTime(),
+     *         new GregorianCalendar(2008,10,10,10,10,10).getTime(),
+     *         new GregorianCalendar(2008,11,10,10,10,10).getTime(),
+     *         new GregorianCalendar(2008,11,10,15,10,10).getTime(),
+     * };
+     * final DateInterval dtitv[] = {
+     *         new DateInterval(date[0].getTime(),date[1].getTime()),
+     *         new DateInterval(date[1].getTime(),date[2].getTime()),
+     *         new DateInterval(date[2].getTime(),date[3].getTime()),
+     * };
+     * final String [] skeletons = {
+     *         DateFormat.YEAR_ABBR_MONTH_DAY,
+     *         DateFormat.MONTH_DAY,
+     *         DateFormat.HOUR_MINUTE,
+     * };
+     * System.out.printf("%-15s%-35s%-35s%-35s%-35s\n", "Skeleton", "from","to","Date Interval in en_US", "Date Interval in Ja");
+     * int i=0;
+     * for (String skeleton:skeletons) {
+     *     System.out.printf("%-15s%-35s%-35s", skeleton,date[i].toString(), date[i+1].toString());
+     *     DateIntervalFormat dtitvfmtEn = DateIntervalFormat.getInstance(skeleton, ULocale.ENGLISH);
+     *     DateIntervalFormat dtitvfmtJa = DateIntervalFormat.getInstance(skeleton, ULocale.JAPANESE);
+     *     System.out.printf("%-35s%-35s\n", dtitvfmtEn.format(dtitv[i]),dtitvfmtJa.format(dtitv[i]));
+     *     i++;
+     * }
+     * /** output of the sample code:
+     *  *********************************************************************************************************************************************************
+     *  Skeleton       from                               to                                 Date Interval in en_US             Date Interval in Ja
+     *  yMMMd          Sat Nov 10 10:10:10 EST 2007       Mon Nov 10 10:10:10 EST 2008       Nov 10, 2007 – Nov 10, 2008        2007年11月10日～2008年11月10日
+     *  MMMMd          Mon Nov 10 10:10:10 EST 2008       Wed Dec 10 10:10:10 EST 2008       November 10 – December 10          11月10日～12月10日
+     *  jm             Wed Dec 10 10:10:10 EST 2008       Wed Dec 10 15:10:10 EST 2008       10:10 AM – 3:10 PM                 10:10～15:10
+     *  *********************************************************************************************************************************************************/
+     *
+ * * @param skeleton the skeleton on which interval format based. * @param locale the given locale * @return a date time interval formatter. @@ -650,7 +697,50 @@ public class DateIntervalFormat extends UFormat { * This is a convenient override of * getInstance(String skeleton, ULocale locale, DateIntervalInfo dtitvinf) * - *

Example code:{@.jcite com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:---dtitvfmtCustomizedExample} + * + *

Example code:

+ * + * 

+     * final Date date[] = {
+     *         new GregorianCalendar(2007,9,10,10,10,10).getTime(),
+     *         new GregorianCalendar(2007,10,10,10,10,10).getTime(),
+     *         new GregorianCalendar(2007,10,10,22,10,10).getTime(),
+     * };
+     * final DateInterval dtitv[] = {
+     *         new DateInterval(date[0].getTime(),date[1].getTime()),
+     *         new DateInterval(date[1].getTime(),date[2].getTime()),
+     * };
+     * final String [] skeletons = {
+     *         DateFormat.YEAR_ABBR_MONTH_DAY,
+     *         DateFormat.HOUR24_MINUTE,
+     * };
+     * System.out.printf("%-15s%-35s%-35s%-45s%-35s\n", "Skeleton", "from","to", "Date Interval in en_US", "Date Interval in Ja");
+     * // Create an empty DateIntervalInfo object
+     * DateIntervalInfo dtitvinf = new DateIntervalInfo(ULocale.ENGLISH);
+     * // Set Date Time internal pattern for MONTH, DAY_OF_MONTH, HOUR_OF_DAY
+     * dtitvinf.setIntervalPattern("yMMMd", Calendar.MONTH, "y 'Diff' MMM d --- MMM d");
+     * dtitvinf.setIntervalPattern("Hm", Calendar.HOUR_OF_DAY, "yyyy MMM d HH:mm ~ HH:mm");
+     * // Set fallback interval pattern
+     * dtitvinf.setFallbackIntervalPattern("{0} ~~~ {1}");
+     * // Get the DateIntervalFormat with the custom pattern
+     * for (String skeleton:skeletons){
+     *     for (int i=0;i<2;i++) {
+     *         System.out.printf("%-15s%-35s%-35s", skeleton,date[i].toString(), date[i+1].toString());
+     *         DateIntervalFormat dtitvfmtEn = DateIntervalFormat.getInstance(skeleton,ULocale.ENGLISH,dtitvinf);
+     *         DateIntervalFormat dtitvfmtJa = DateIntervalFormat.getInstance(skeleton,ULocale.JAPANESE,dtitvinf);
+     *         System.out.printf("%-45s%-35s\n", dtitvfmtEn.format(dtitv[i]),dtitvfmtJa.format(dtitv[i]));
+     *     }
+     * }
+     * /** output of the sample code:
+     *  *************************************************************************************************************************************************************************
+     *   Skeleton       from                               to                                 Date Interval in en_US                       Date Interval in Ja
+     *   yMMMd          Wed Oct 10 10:10:10 EDT 2007       Sat Nov 10 10:10:10 EST 2007       2007 Diff Oct 10 --- Nov 10                  2007 Diff 10月 10 --- 11月 10
+     *   yMMMd          Sat Nov 10 10:10:10 EST 2007       Sat Nov 10 22:10:10 EST 2007       Nov 10, 2007                                 2007年11月10日
+     *   Hm             Wed Oct 10 10:10:10 EDT 2007       Sat Nov 10 10:10:10 EST 2007       10/10/2007, 10:10 ~~~ 11/10/2007, 10:10      2007/10/10 10:10 ~~~ 2007/11/10 10:10
+     *   Hm             Sat Nov 10 10:10:10 EST 2007       Sat Nov 10 22:10:10 EST 2007       2007 Nov 10 10:10 ~ 22:10                    2007 11月 10 10:10 ~ 22:10
+     *  *************************************************************************************************************************************************************************/
+     *
+ * * @param skeleton the skeleton on which interval format based. * @param locale the given locale * @param dtitvinf the DateIntervalInfo object to be adopted. diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/text/DateTimePatternGenerator.java b/icu4j/main/core/src/main/java/com/ibm/icu/text/DateTimePatternGenerator.java index 44c884dae55..9c16bf33acf 100644 --- a/icu4j/main/core/src/main/java/com/ibm/icu/text/DateTimePatternGenerator.java +++ b/icu4j/main/core/src/main/java/com/ibm/icu/text/DateTimePatternGenerator.java @@ -617,7 +617,85 @@ public class DateTimePatternGenerator implements FreezableExample code:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---getBestPatternExample} + * + * + *

Example code:

+ * + * 
+     * import java.util.Date;
+     *
+     * import com.ibm.icu.text.DateFormat;
+     * import com.ibm.icu.text.DateTimePatternGenerator;
+     * import com.ibm.icu.text.SimpleDateFormat;
+     * import com.ibm.icu.util.GregorianCalendar;
+     * import com.ibm.icu.util.TimeZone;
+     * import com.ibm.icu.util.ULocale;
+     * ...
+     * final String[] skeletons = {
+     *         "yQQQQ", // year + full name of quarter, i.e., 4th quarter 1999
+     *         "yMMMM", // year + full name of month, i.e., October 1999
+     *         "MMMMd", // full name of month + day of the month, i.e., October 25
+     *         "hhmm",  // 12-hour-cycle format, i.e., 1:32 PM
+     *         "jjmm"   // preferred hour format for the given locale, i.e., 24-hour-cycle format for fr_FR
+     * };
+     * final ULocale[] locales = {
+     *         new ULocale ("en_US"),
+     *         new ULocale ("fr_FR"),
+     *         new ULocale ("zh_CN"),
+     * };
+     * DateTimePatternGenerator dtfg = null;
+     * Date date= new GregorianCalendar(1999,9,13,23,58,59).getTime();
+     * System.out.printf("%-20s%-35s%-35s%-35s\n\n", "Skeleton", "en_US", "fr_FR","zh_CN");
+     * for (String skeleton:skeletons) {
+     *     System.out.printf("%-20s", skeleton);
+     *     for (ULocale locale:locales) {
+     *         // create a DateTimePatternGenerator instance for given locale
+     *         dtfg = DateTimePatternGenerator.getInstance(locale);
+     *         // use getBestPattern method to get the best pattern for the given skeleton
+     *         String pattern = dtfg.getBestPattern(skeleton);
+     *         // Constructs a SimpleDateFormat with the best pattern generated above and the given locale
+     *         SimpleDateFormat sdf = new SimpleDateFormat(pattern, locale);
+     *         // Get the format of the given date
+     *         System.out.printf("%-35s",sdf.format(date));
+     *     }
+     *     System.out.println("\n");
+     * }
+     * /** output of the sample code:
+     *  *************************************************************************************************************
+     *    Skeleton            en_US                              fr_FR                              zh_CN
+     *    yQQQQ               4th quarter 1999                   4e trimestre 1999                  1999年第四季度
+     *    yMMMM               October 1999                       octobre 1999                       1999年10月
+     *    MMMMd               October 13                         13 octobre                         10月13日
+     *    hhmm                11:58 PM                           11:58 PM                           下午11:58
+     *    jjmm                11:58 PM                           23:58                              下午11:58
+     *  **************************************************************************************************************/
+     * // Use DateTime.getPatternInstance to produce the same Date/Time format with predefined constant field value
+     * final String[] dtfskeleton = {
+     *         DateFormat.YEAR_QUARTER, // year + full name of quarter, i.e., 4th quarter 1999
+     *         DateFormat.YEAR_MONTH,   // year + full name of month, i.e., October 1999
+     *         DateFormat.MONTH_DAY     // full name of month + day of the month, i.e., October 25
+     * };
+     * System.out.printf("%-20s%-35s%-35s%-35s\n\n", "Skeleton", "en_US", "fr_FR","zh_CN");
+     * for (String skeleton:dtfskeleton) {
+     *     System.out.printf("%-20s", skeleton);
+     *     for (ULocale locale:locales) {
+     *         // Use DateFormat.getPatternInstance to get the date/time format for the locale,
+     *         // and apply the format to the given date
+     *         String df=DateFormat.getPatternInstance(skeleton,locale).format(date);
+     *         System.out.printf("%-35s",df);
+     *     }
+     *     System.out.println("\n");
+     * }
+     *
+     * /** output of the sample code:
+     *  ************************************************************************************************************
+     *  Skeleton            en_US                              fr_FR                              zh_CN
+     *  yQQQQ               4th quarter 1999                   4e trimestre 1999                  1999年第四季度
+     *  yMMMM               October 1999                       octobre 1999                       1999年10月
+     *  MMMMd               October 13                         13 octobre                         10月13日
+     *  ************************************************************************************************************/
+     *
+ * * @param skeleton The skeleton is a pattern containing only the variable fields. * For example, "MMMdd" and "mmhh" are skeletons. * @return Best pattern matching the input skeleton. @@ -802,7 +880,31 @@ public class DateTimePatternGenerator implements Freezable * Note that single-field patterns (like "MMM") are automatically added, and * don't need to be added explicitly! - * *

Example code:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---addPatternExample} + * + * + *

Example code:

+ * + * 
+     * Date date= new GregorianCalendar(1999,9,13,23,58,59).getTime();
+     * ULocale locale = ULocale.FRANCE;
+     * // Create an DateTimePatternGenerator instance for the given locale
+     * DateTimePatternGenerator gen = DateTimePatternGenerator.getInstance(locale);
+     * SimpleDateFormat format = new SimpleDateFormat(gen.getBestPattern("MMMMddHmm"), locale);
+     * DateTimePatternGenerator.PatternInfo returnInfo = new DateTimePatternGenerator.PatternInfo();
+     * // Add '. von' to the existing pattern
+     * gen.addPattern("dd'. von' MMMM", true, returnInfo);
+     * // Apply the new pattern
+     * format.applyPattern(gen.getBestPattern("MMMMddHmm"));
+     * System.out.println("New Pattern for FRENCH: "+format.toPattern());
+     * System.out.println("Date Time in new Pattern: "+format.format(date));
+     *
+     * /** output of the sample code:
+     *  **************************************************************************************************
+     *  New Pattern for FRENCH: dd. 'von' MMMM HH:mm
+     *  Date Time in new Pattern: 13. von octobre 23:58
+     *  *************************************************************************************************/
+     *
+ * * @param pattern Pattern to add. * @param override When existing values are to be overridden use true, otherwise * use false. @@ -987,7 +1089,45 @@ public class DateTimePatternGenerator implements FreezableExample code:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---replaceFieldTypesExample} + * + * + *

Example code:

+ * + * 
+     * Date date= new GregorianCalendar(1999,9,13,23,58,59).getTime();
+     * TimeZone zone = TimeZone.getTimeZone("Europe/Paris");
+     * ULocale locale = ULocale.FRANCE;
+     * DateTimePatternGenerator gen = DateTimePatternGenerator.getInstance(locale);
+     * SimpleDateFormat format = new SimpleDateFormat("EEEE d MMMM y HH:mm:ss zzzz",locale);
+     * format.setTimeZone(zone);
+     * String pattern = format.toPattern();
+     * System.out.println("Pattern before replacement:");
+     * System.out.println(pattern);
+     * System.out.println("Date/Time format in fr_FR:");
+     * System.out.println(format.format(date));
+     * // Replace zone "zzzz" in the pattern with "vvvv"
+     * String newPattern = gen.replaceFieldTypes(pattern, "vvvv");
+     * // Apply the new pattern
+     * format.applyPattern(newPattern);
+     * System.out.println("Pattern after replacement:");
+     * System.out.println(newPattern);
+     * System.out.println("Date/Time format in fr_FR:");
+     * System.out.println(format.format(date));
+     *
+     * /** output of the sample code:
+     * ***************************************************************************************************
+     *  Pattern before replacement:
+     *  EEEE d MMMM y HH:mm:ss zzzz
+     *  Date/Time format in fr_FR:
+     *  jeudi 14 octobre 1999 05:58:59 heure avancée d’Europe centrale
+     *  Pattern after replacement:
+     *  EEEE d MMMM y HH:mm:ss vvvv
+     *  Date/Time format in fr_FR:
+     *  jeudi 14 octobre 1999 05:58:59 heure de l’Europe centrale
+     *
+     * **************************************************************************************************/
+     *
+ * * @param pattern input pattern * @param skeleton For the pattern to match to. * @return pattern adjusted to match the skeleton fields widths and subtypes. diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/text/PluralFormat.java b/icu4j/main/core/src/main/java/com/ibm/icu/text/PluralFormat.java index fb65a03b145..5c6380106b8 100644 --- a/icu4j/main/core/src/main/java/com/ibm/icu/text/PluralFormat.java +++ b/icu4j/main/core/src/main/java/com/ibm/icu/text/PluralFormat.java @@ -295,7 +295,80 @@ public class PluralFormat extends UFormat { * locale. * The locale will be used to get the set of plural rules and for * standard number formatting. - *

Example code:{@.jcite com.ibm.icu.samples.text.pluralformat.PluralFormatSample:---PluralFormatExample} + * + * + *

Example code:

+ * + * 
+     * import java.text.FieldPosition;
+     *
+     * import com.ibm.icu.text.MessageFormat;
+     * import com.ibm.icu.text.PluralFormat;
+     * import com.ibm.icu.util.ULocale;
+     * ...
+     * ULocale locEn = new ULocale("en");
+     * ULocale locSl = new ULocale("sl");
+     *
+     * String patEn = "one{dog} other{dogs}";                      // English 'dog'
+     * String patSl = "one{pes} two{psa} few{psi} other{psov}";    // Slovenian translation of dog in Plural Form
+     *
+     * // Create a new PluralFormat for a given locale locale and pattern string
+     * PluralFormat plfmtEn = new PluralFormat(locEn, patEn);
+     * PluralFormat plfmtSl = new PluralFormat(locSl, patSl);
+     * // Constructs a MessageFormat for the specified locale and pattern.
+     * MessageFormat msgfmtEn = new MessageFormat("{0,number} {1}", locEn);
+     * MessageFormat msgfmtSl = new MessageFormat("{0,number} {1}", locSl);
+     *
+     * final int[] numbers = {0, 1, 2, 3, 4, 5, 10, 100, 101, 102};
+     * System.out.println("Output by using PluralFormat and MessageFormat API\n");
+     * System.out.printf("%-16s%-16s%-16s\n", "Number", "English", "Slovenian");
+     *
+     * // Use MessageFormat.format () to format the objects and appends to the given StringBuffer
+     * for (int num : numbers) {
+     *     StringBuffer msgEn = new StringBuffer();
+     *     StringBuffer msgSl = new StringBuffer();
+     *
+     *     msgfmtEn.format(new Object[] {num, plfmtEn.format(num)}, msgEn, new FieldPosition(0));
+     *     msgfmtSl.format(new Object[] {num, plfmtSl.format(num)}, msgSl, new FieldPosition(0));
+     *
+     *     System.out.printf("%-16s%-16s%-16s\n", num, msgEn, msgSl);
+     * }
+     *
+     * System.out.println();
+     *
+     * // Equivalent code with message format pattern
+     * String msgPatEn = "{0,plural, one{# dog} other{# dogs}}";
+     * String msgPatSl = "{0,plural, one{# pes} two{# psa} few{# psi} other{# psov}}";
+     *
+     * MessageFormat altMsgfmtEn = new MessageFormat(msgPatEn, locEn);
+     * MessageFormat altMsgfmtSl = new MessageFormat(msgPatSl, locSl);
+     * System.out.println("Same Output by using MessageFormat API only\n");
+     * System.out.printf("%-16s%-16s%-16s\n", "Number", "English", "Slovenian");
+     * for (int num : numbers) {
+     *     StringBuffer msgEn = new StringBuffer();
+     *     StringBuffer msgSl = new StringBuffer();
+     *
+     *     altMsgfmtEn.format(new Object[] {num}, msgEn, new FieldPosition(0));
+     *     altMsgfmtSl.format(new Object[] {num}, msgSl, new FieldPosition(0));
+     *
+     *     System.out.printf("%-16s%-16s%-16s\n", num, msgEn, msgSl);
+     * }
+     * /** output of the sample code:
+     *  ********************************************************************
+     *   Number          English         Slovenian
+     *   0               0 dogs          0 psov
+     *   1               1 dog           1 pes
+     *   2               2 dogs          2 psa
+     *   3               3 dogs          3 psi
+     *   4               4 dogs          4 psi
+     *   5               5 dogs          5 psov
+     *   10              10 dogs         10 psov
+     *   100             100 dogs        100 psov
+     *   101             101 dogs        101 pes
+     *   102             102 dogs        102 psa
+     *  *******************************************************************/
+     *
+ * * @param ulocale the PluralFormat will be configured with * rules for this locale. This locale will also be used for standard * number formatting. diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/text/RuleBasedNumberFormat.java b/icu4j/main/core/src/main/java/com/ibm/icu/text/RuleBasedNumberFormat.java index 903e546a51a..548e8d82327 100644 --- a/icu4j/main/core/src/main/java/com/ibm/icu/text/RuleBasedNumberFormat.java +++ b/icu4j/main/core/src/main/java/com/ibm/icu/text/RuleBasedNumberFormat.java @@ -419,7 +419,7 @@ import com.ibm.icu.util.UResourceBundleIterator; * Format the number unchanged * * - * []
[|] + * []
[|] * in normal rule * *
    diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/util/BasicTimeZone.java b/icu4j/main/core/src/main/java/com/ibm/icu/util/BasicTimeZone.java index 50483f0799c..712c9391bda 100644 --- a/icu4j/main/core/src/main/java/com/ibm/icu/util/BasicTimeZone.java +++ b/icu4j/main/core/src/main/java/com/ibm/icu/util/BasicTimeZone.java @@ -35,7 +35,34 @@ public abstract class BasicTimeZone extends TimeZone { /** * {@icu} Returns the first time zone transition after the base time. - *

    Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getNextTransitionExample} + * + * + *

    Example code:

    + * + * 
    +     * System.out.println("### Iterates time zone transitions in America/Los_Angeles starting 2005-01-01 and forward");
+     *
+     * // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
+     * BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);
+     *
+     * // Date format for the wall time
+     * SimpleDateFormat wallTimeFmt = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss z", ULocale.US);
+     * wallTimeFmt.setTimeZone(btz);
+     *
+     * long start = 1104537600000L;    // 2005-01-01 0:00 UTC
+     * for (int i = 0; i < 5; i++) {   // Up to 5 transitions
+     *     TimeZoneTransition trans = btz.getNextTransition(start, false /* not including start time */);
+     *
+     *     // Display the transition time and offset information
+     *     long transTime = trans.getTime();
+     *     System.out.println(wallTimeFmt.format(new Date(transTime - 1)) + " -> " + wallTimeFmt.format(new Date(transTime)));
+     *     System.out.println(" - Before (Offset/Save): " + trans.getFrom().getRawOffset() + "/" + trans.getFrom().getDSTSavings());
+     *     System.out.println(" - After  (Offset/Save): " + trans.getTo().getRawOffset() + "/" + trans.getTo().getDSTSavings());
+     *
+     *     // Update start time for next transition
+     *     start = transTime;
+     * }
+     *
    * * @param base The base time. * @param inclusive Whether the base time is inclusive or not. @@ -50,7 +77,34 @@ public abstract class BasicTimeZone extends TimeZone { /** * {@icu} Returns the last time zone transition before the base time. - *

    Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getPreviousTransitionExample} + * + * + *

    Example code:

    + * + * 
    +     * System.out.println("### Iterates time zone transitions in America/Los_Angeles starting 2010-01-01 and backward");
+     *
+     * // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
+     * BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);
+     *
+     * // Date format for the wall time
+     * SimpleDateFormat wallTimeFmt = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss z", ULocale.US);
+     * wallTimeFmt.setTimeZone(btz);
+     *
+     * long start = 1262304000000L;    // 2010-01-01 0:00 UTC
+     * for (int i = 0; i < 5; i++) {   // Up to 5 transitions
+     *     TimeZoneTransition trans = btz.getPreviousTransition(start, false /* not including start time */);
+     *
+     *     // Display the transition time and offset information
+     *     long transTime = trans.getTime();
+     *     System.out.println(wallTimeFmt.format(new Date(transTime - 1)) + " -> " + wallTimeFmt.format(new Date(transTime)));
+     *     System.out.println(" - Before (Offset/Save): " + trans.getFrom().getRawOffset() + "/" + trans.getFrom().getDSTSavings());
+     *     System.out.println(" - After  (Offset/Save): " + trans.getTo().getRawOffset() + "/" + trans.getTo().getDSTSavings());
+     *
+     *     // Update start time for next transition
+     *     start = transTime;
+     * }
+     *
    * * @param base The base time. * @param inclusive Whether the base time is inclusive or not. @@ -68,7 +122,37 @@ public abstract class BasicTimeZone extends TimeZone { * This method returns true when all of transition times, from/to standard * offsets and DST savings used by this time zone match the other in the * time range. - *

    Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---hasEquivalentTransitionsExample} + * + * + *

    Example code:

    + * + * 
    +     * System.out.println("### Compare America/New_York and America/Detroit since year 1970");
+     *
+     * // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
+     * BasicTimeZone tzNewYork = (BasicTimeZone)TimeZone.getTimeZone("America/New_York", TimeZone.TIMEZONE_ICU);
+     * BasicTimeZone tzDetroit = (BasicTimeZone)TimeZone.getTimeZone("America/Detroit", TimeZone.TIMEZONE_ICU);
+     *
+     * GregorianCalendar cal = new GregorianCalendar(TimeZone.getTimeZone("Etc/GMT"));
+     *
+     * // Compare these time zones every 10 years since year 1970 up to year 2009
+     * for (int startYear = 1970; startYear <= 2000; startYear += 10) {
+     *     long start, end;
+     *
+     *     cal.set(startYear, Calendar.JANUARY, 1, 0, 0, 0);
+     *     cal.set(Calendar.MILLISECOND, 0);
+     *     start = cal.getTimeInMillis();
+     *
+     *     // Set the end time to the end of startYear + 9
+     *     int endYear = startYear + 9;
+     *     cal.set(endYear + 1, Calendar.JANUARY, 1, 0, 0, 0);
+     *     end = cal.getTimeInMillis() - 1;
+     *
+     *     // Check if these two zones have equivalent time zone transitions for the given time range
+     *     boolean isEquivalent = tzNewYork.hasEquivalentTransitions(tzDetroit, start, end);
+     *     System.out.println(startYear + "-" + endYear + ": " + isEquivalent);
+     * }
+     *
    * * @param tz The instance of TimeZone * @param start The start time of the evaluated time range (inclusive) @@ -227,7 +311,22 @@ public abstract class BasicTimeZone extends TimeZone { * instance for the initial rule. The rest will be either * AnnualTimeZoneRule or TimeArrayTimeZoneRule * instances representing transitions. - *

    Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getTimeZoneRulesExample} + * + * + *

    Example code:

    + * + * 
    +     * System.out.println("### Extracts time zone rules used by America/Los_Angeles since year 2005");
+     *
+     * // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
+     * BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);
+     * long since = 1104537600000L;    // 2005-01-01 0:00 UTC
+     * TimeZoneRule[] rules = btz.getTimeZoneRules(since);
+     * System.out.println("Rule(initial): " + rules[0]);
+     * for (int i = 1; i < rules.length; i++) {
+     *     System.out.println("Rule: " + rules[i]);
+     * }
+     *
    * * @param start The start time (inclusive). * @return The array of TimeZoneRule which represents this diff --git a/icu4j/pom.xml b/icu4j/pom.xml index faeb96a96fc..e966f53666e 100644 --- a/icu4j/pom.xml +++ b/icu4j/pom.xml @@ -388,18 +388,10 @@ 256m 256m - - -J-Djcitesourcepath=${icu4j.api.doc.root.dir}/samples/src/main/java${path.separator}${icu4j.api.doc.root.dir}/demos/src/main/java${path.separator}${icu4j.api.doc.root.dir}/main/core/src/main/java - -J-Dfile.encoding=UTF-8 - -J-Djciteverbose=true - com.ibm.icu.dev.tool.docs.ICUTaglet - - ch.arrenbrecht.jcite.JCiteTaglet - @@ -408,23 +400,6 @@ tools_build ${project.version} - - - org.mcraig - jcite - 1.13.0 - - - - commons-discovery - commons-discovery - 0.5 - - - commons-logging - commons-logging - 1.2 - diff --git a/icu4j/stylesheet8.css b/icu4j/stylesheet8.css index 598b0a475b3..c0352f06218 100644 --- a/icu4j/stylesheet8.css +++ b/icu4j/stylesheet8.css @@ -576,95 +576,3 @@ div.block div.block span.interfaceName { div.contentContainer ul.blockList li.blockList h2{ padding-bottom:0px; } - -/* Styles for JCite */ -pre.java /* container for citations */ - { - border-style: solid; - border-width: 1px; - border-color: DarkGray; - margin: 1.5em 1.5em 1.5em 1.5em; - padding: 1em; - background-color: cornsilk; - } - -tt.java /* single cited line in JCite's -tt mode */ - { - border-style: solid; - border-width: 1px; - border-color: DarkGray; - margin: 1.5em 1.5em 1.5em 1.5em; - background-color: cornsilk; - } - -span.j-blk /* block comment */ -{ - color: DarkGreen; -} - -span.j-cmt /* line comment */ -{ - color: DarkGreen; -} - -span.j-key /* keyword */ -{ - /* font-weight:bold; */ - color: Purple; - font-weight: bold; -} - -span.j-str /* string constants */ -{ - color: Blue; -} - -span.j-chr /* char constants */ -{ - color: Blue; -} - -span.j-num /* number constants */ -{ -} - -span.j-sym /* symbols, punctuation */ -{ -} - -span.j-typ /* primitive types */ -{ - color: Purple; - font-weight: bold; -} - -span.j-jdoc /* javadoc */ -{ - color: DarkSlateBlue; -} - -span.j-jdoc-key /* javadoc keyword */ -{ - color: MediumSlateBlue; - font-weight: bold; -} - -span.j-jdoc-html /* javadoc html tag */ -{ - color: SlateGray; -} - -span.j-jdoc-link /* javadoc link */ -{ - color: Blue; -} - -span.j-undef /* undefined */ -{ -} - -span.j-hl /* highlight */ -{ - text-decoration: none; - background-color: #FFFFB0; -}