automate checking API tags vs. ifdef guards

Description

For the BRS task "Check non-stable API macros (U_HIDE_DRAFT_API and others)" = http://site.icu-project.org/processes/release/tasks/docs#TOC-Verify-that-draft-is-surrounded-by-ifndef-U_HIDE_DRAFT_API-etc

Idea:

  • Write a script like the header test (or extend that one).

  • Make it work. Add it to a build bot.

  • For each public header file:

  • Write a temporary .cpp file with one line like #include "unicode/locid.h"

  • Preprocess it (only) preserving comments. ~/icu$ clang++ -Imine/src/icu4c/source/common -C -E -o testinclude-normal.i testinclude.cpp

  • For each of {draft, deprecated, internal, system, obsolete} preprocess it again with the corresponding ifdef guard set to "hide". For example, for draft: clang++ -Imine/src/icu4c/source/common -C -E -DU_HIDE_DRAFT_API=1 -o testinclude-draft.i testinclude.cpp

  • Check that the hide-draft output contains no @draft. grep '@draft' testinclude-draft.i should be empty.

  • Diff the normal vs. hide output. diff -u testinclude-normal.i testinclude-draft.i > diff-draft.txt

  • Check that this diff does not contain any of the other API tags. egrep '^-.*@(stable|deprecated|internal|system|obsolete)' -A 3 diff-draft.txt should be empty.

In this case, right now, the output is not empty but rather

1 2 3 4 - * @internal - */ - ULOC_AVAILABLE_COUNT -

In other words, this constant is guarded by U_HIDE_DRAFT_API but should be guarded by U_HIDE_INTERNAL_API.

Issue: There are some APIs (some enums, enum constants, virtual methods) that we cannot guard with ifdefs.

Solution for this: Add another ifdef guard like U_FORCE_HIDE_DRAFT_API which cannot be used for real, but which we can add for documentation and to make the grep above come out empty by setting this guard also on the preprocessor command line.

Status

Assignee

Markus Scherer

Reporter

Markus Scherer

Labels

None

Reviewer

None

Time Needed

Hours

Start date

None

Components

Fix versions

Priority

major