Skip to content

Commit

Permalink
ICU-23041 Hard-code the code citations and remove jcite
Browse files Browse the repository at this point in the history
  • Loading branch information
@mihnita
mihnita committed Feb 6, 2025
1 parent 362a4aa commit 5d7f0b8
Show file tree
Hide file tree
Showing 10 changed files with 414 additions and 169 deletions.
3 changes: 0 additions & 3 deletions docs/processes/release/tasks/docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
<https://icu.unicode.org/setup/java/ant#TOC-Building-ICU4J-API-Reference-Document-with-JCite>

Build the API documentation pages for the new release:

```
Expand Down
5 changes: 0 additions & 5 deletions docs/processes/release/tasks/release-build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@ compiled with Java system libraries from JRE 7.*</span>
* Java Runtime Environment 7 (used as bootclasspath for cross-compilation)
* Apache Ant 1.10.x (the latest available version)
\[<http://ant.apache.org/>\]
* JCite 1.13.0 \[<https://arrenbrecht.ch/jcite/>\]

### Other Prerequisites only for GA

Expand All @@ -56,9 +55,6 @@ compiled with Java system libraries from JRE 7.*</span>
### 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.
Expand Down Expand Up @@ -150,7 +146,6 @@ compiled with Java system libraries from JRE 7.*</span>
[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
Expand Down
34 changes: 1 addition & 33 deletions docs/userguide/dev/codingguidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<icu4j_root>/samples/src` directory,
although you can cite any source fragment from source files in
`<icu4j_root>/demos/src`, `<icu4j_root\>/main/core/*/src`,
`<icu4j_root>/main/test/*/src`.
* A sample code should use package name -
`com.ibm.icu.samples.<subpackage>.<facility>`. `<subpackage>` is corresponding
to the target ICU API class's package, that is, one of lang/math/text/util.
`<facility>` 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`:
Expand Down
94 changes: 92 additions & 2 deletions icu4j/main/core/src/main/java/com/ibm/icu/text/DateIntervalFormat.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -570,7 +570,54 @@ private DateIntervalFormat(String skeleton, ULocale locale,
* This is a convenient override of
* getInstance(String skeleton, ULocale locale)
*
* <p>Example code:{@.jcite com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:---dtitvfmtPreDefinedExample}
* <!-- From: com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:dtitvfmtPreDefinedExample -->
* <p>Example code:<p>
*
* <pre>
* 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
* *********************************************************************************************************************************************************<code>/</code>
* </pre>
*
* @param skeleton the skeleton on which interval format based.
* @param locale the given locale
* @return a date time interval formatter.
Expand Down Expand Up @@ -650,7 +697,50 @@ public static final DateIntervalFormat getInstance(String skeleton,
* This is a convenient override of
* getInstance(String skeleton, ULocale locale, DateIntervalInfo dtitvinf)
*
* <p>Example code:{@.jcite com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:---dtitvfmtCustomizedExample}
* <!-- From: com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:dtitvfmtCustomizedExample -->
* <p>Example code:<p>
*
* <pre>
* 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
* *************************************************************************************************************************************************************************<code>/</code>
* </pre>
*
* @param skeleton the skeleton on which interval format based.
* @param locale the given locale
* @param dtitvinf the DateIntervalInfo object to be adopted.
Expand Down
Loading

0 comments on commit 5d7f0b8

Please sign in to comment.