APIs & Docs


Update API status comments

ICU4C

  1. Note: for ICU4C 49m2 or later, will require Doxygen 1.7.5.1 or later ( see #8862 )
    1. To update Doxygen, first download binary or source release here
    2. Unpack the release, and run something like
       "configure --prefix /usr/local" (to install into /usr/local/bin etc )
      (Note for the binary release, 'configure' just builds an installer.)
    3. Run "make install" with appropriate permission (perhaps 
      "sudo make install".)
    4. Verify that 'doxygen --version' gives the correct number.
  2. Update the API documentation in all header files (.h file) to have correct @draft/@stable/@deprecated labels.
  3. Update docmain.h
  4. ./configure
  5. make doc
  6. Follow instructions in tools/release/java/readme.txt to generate API status change report.
  7. Make sure that ICU headers work with U_HIDE_DRAFT_API and other such switches.
  8. Verify that U_DRAFT and U_STABLE match the @draft and @stable tags (same for other such pairs declaration macro vs. tag).
    1. For example, on Linux:
    2. grep --recursive --include="*.h" --exclude-dir=".svn" -e "@deprecated" -A 5 . > at-deprecated.txt
    3. grep --recursive --include="*.h" --exclude-dir=".svn" -e "U_DEPRECATED" -B 5 -A 1 . > u_deprecated.txt
    4. Do this for draft, deprecated, obsolete, internal.
    5. For @stable, we either verify by cleaning up all others or we need to write a script.

ICU4J

Update the API documentation to have correct @draft/@stable/@deprecated labels. See the User Guide, ICU Architectural Design, ICU API compatibility.

On ICU4J, run com.ibm.icu.dev.tool.docs.CheckTags (see file for instructions). This requires a JDK with javadoc available. The tool will need to change to reflect the release number to search for.

To check the API status changes, run the ant target "apireport" to gerate the report since the previous official release.

Make sure @draft APIs are also marked as @provisional. For example:

 * @draft ICU 4.0
 * @provisional This API might change or be removed in a future release.

Make sure @internal APIs are also marked as @deprecated:

 * @internal
 * @deprecated This API is ICU internal only.

Update the API Change Report

ICU4C

  1. Update the API documentation in all header files (.h file) to have correct @draft/@stable/@deprecated/@obsolete labels.
  2. Update docmain.h
  3. ./configure
  4. make docs
  5. Folow instructions in tools/release/java/readme.txt.

ICU4J

  1. Run ant task "apireport" at <icu4j_root>
  2. Above will produce API change report file <icu4j_root>/out/icu4j_compare_xxx_yyy.html
  3. Make sure there are any new doc tag errors are reported. (As of ICU 4.4, ArabicShaping constants do not have proper tags - otherwise, clean)
  4. Copy generated report file to <icu4j_root>/APIChangeReport.html and check it in.

Once official release version is shipped, we need to keep API signature information file for next iteration. This is not done for milestone releases, only after the final official release.

  1. Run ant task "gatherapi" at <icu4j_root>
  2. Above will produce API signature information file <icu4j_root>/out/icu4jxx.api2.gz
  3. Copy icu4jxxapi2.gz to <icu4j_root>/tools/build and add it to the repository

Check in API signature data file (ICU4J)

Once APIs are frozen for a reference release, we should check in the API signature data file into the repository. The data file will be used for future API change report.
  1. Run ant task "gatherapi" at <icu4j_root>
  2. The output file icu4j<ver>.api2.gz is created in <icu4j_root>/out directory.
  3. Copy the output .gz file to <icu4j_root>/tools directory and check in the file to the repository.
Note: This task is only necessary for reference releases, because we won't change public APIs in maintenance releases.

Verify that @draft is surrounded by #ifndef U_HIDE_DRAFT_API etc.

In ICU4C, we want every (consecutive group of) @draft API to be surrounded by #ifndef U_HIDE_DRAFT_API. This allows users to -DU_HIDE_DRAFT_API to make sure they don't use unstable API.

#ifndef U_HIDE_DRAFT_API

/** @draft ICU 51 */
U_CAPI u_newFunction1();

/** @draft ICU 51 */
U_CAPI u_newFunction2();

#endif /* U_HIDE_DRAFT_API */

Same for @deprecated & #ifndef U_HIDE_DEPRECATED_API  ..  #endif  /* U_HIDE_DEPRECATED_API */

Same for @internal & #ifndef U_HIDE_INTERNAL_API  ..  #endif  /* U_HIDE_INTERNAL_API */

Same for @system & #ifndef U_HIDE_SYSTEM_API  ..  #endif  /* U_HIDE_SYSTEM_API */

Same for @obsolete & #ifndef U_HIDE_OBSOLETE_API  ..  #endif  /* U_HIDE_OBSOLETE_API */

Task

We don't have tools for this. Use "grep" or similar on the public common, i18n, io header files. Use grep options like -A 3, -B 2 and -C 3 for context After, Before, and Around the matching line.

a) For each of these API status tags, for each API that is tagged with it, verify that the API is surrounded by the appropriate #ifndef..#endif.

Note: It is best to not use one single guard for APIs with different ICU versions, since they will become stable and thus lose their guards at different times. Use one #ifndef..#endif guard per API status and ICU version.

b) For each of these U_HIDE_..._API guards, verify that it only and exactly surrounds APIs with the corresponding status tag. In particular, make sure that U_HIDE_DRAFT_API does not surround (newly) @stable API.

Caution

  • We cannot #ifndef-guard virtual methods because that makes the vtable incompatible.
    • /* Cannot use #ifndef U_HIDE_DRAFT_API for the following draft method since it is virtual. */
  • When you #ifndef-guard enum constants, normally the following unguarded ones (e.g., a _COUNT or _LIMIT) should retain the same numeric values as if the guard was absent.

Update udraft.h, usystem.h, uintrnl.h, uobslete.h and udeprctd.h

In ICU 49 and above, these header files and the gendraft/genheaders.pl tool are gone. (Ticket #8571)

Instructions for ICU4C 4.8.x and below:
  1. make doc
  2. cd source/tools/gendraft ; make install-headers
  3. Double check the modified files in <icu>/source/common/unicode folder and commit.

Compare ICU4J APIs with JDK

Run the ICU4J versus JDK API comparison tool against the target JDK (anything that will come out before our next release, basically) with the tool com.ibm.icu.dev.tool.docs.ICUJDKCompare and make sure ICU4J adequately covers the JDK API for the classes we replicate.

Build API documentations

... and publish them to the ICU public site.

ICU4C

Build the API documentation pages for the new release. Run Doxygen to create the javadoc files. Create icu4c-X_X_X-docs.zip

Note: for ICU4C 49m2 or later, will require Doxygen 1.7.5.1 or later ( see #8862 )

ICU4J

Build the API documentation pages for the new release. "ant docs"

Note: JCite must be installed: http://site.icu-project.org/setup/java/ant#TOC-Building-ICU4J-API-Reference-Document-with-JCite

Update the Readme.html for GA

If there are any last second changes. Make sure to document especially items that affect software that is currently compiled with the previous version of ICU. Update build/installation instructions as necessary.

Comments