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

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.

Assignee

Markus Scherer

Reporter

Markus Scherer

Components

Labels

None

Reviewer

None

Priority

major

Time Needed

Hours

Fix versions

Configure