ICU-21329 doxygen: U_SHOW_DRAFT_API=1 / U_SHOW_INTERNAL_API=1

[srl295]

ICU-21329

didn't do forensics on this to see where it regressed (seems like a regression)

[markusicu]

Other drafts show up fine. Why would utypes.h be different?

Anyway, the docs build failed: https://travis-ci.org/github/unicode-org/icu/jobs/735832260

Preprocessing /home/travis/build/unicode-org/icu/icu4c/s/home/travis/build/unicode-org/icu/icu4c/source/common/unicode/utypes.h:74: warning: documentation for unknown define U_HIDE_DRAFT_API found.

/home/travis/build/unicode-org/icu/icu4c/source/common/unicode/utypes.h:79: warning: documentation for unknown define U_HIDE_INTERNAL_API found.

[srl295]

https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/utypes_8h.html#a06945159db789670a11e785b4f691b41

in ICU 67, you can see that the docs presume:

#define U_HIDE_DRAFT_API   1

[markusicu]

https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/utypes_8h.html#a06945159db789670a11e785b4f691b41

in ICU 67, you can see that the docs presume:

#define U_HIDE_DRAFT_API   1

Yes, in the rc version, too: https://unicode-org.github.io/icu-docs/apidoc/dev/icu4c/utypes_8h.html#a06945159db789670a11e785b4f691b41

However, only for some subset of headers, because other drafts are visible: https://unicode-org.github.io/icu-docs/apidoc/dev/icu4c/classicu_1_1LocaleMatcher.html#a378c18e66f136e914cc1edcdb0c6a352

And the API change report includes newly draft APIs: https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/maint/maint-68/icu4c/APIChangeReport.html#added

Just not (at least) this one new UErrorCode value.

[markusicu]

Note: uconfig.h has

#ifndef U_DEFAULT_SHOW_DRAFT
#define U_DEFAULT_SHOW_DRAFT 1
#endif

and utypes.h includes that first. That's how by default everyone sees and can use draft APIs.

[markusicu]

ping

[srl295]

@markusicu sorry have not had a chance to look at this… could someone else take a look?

[markusicu]

@markusicu sorry have not had a chance to look at this… could someone else take a look?

Please send an email to the team list.

[markusicu]

FYI It would be good to hide internal APIs from docs & change reports, so we don't want to turn on U_SHOW_INTERNAL_API. The Java API change report already excludes internal API I believe.

We should show all drafts and hide all internals.

[markusicu]

We should show all drafts and hide all internals.

PS: Of course, not all internals have the hide-internal guard because ICU headers wouldn't compile that way.

[markusicu]

Otherwise, seems OK.

There is a big open question here of why definitions in utypes.h seem to be treated differently from ones elsewhere. And the changes don't really make sense to me: The drafts already show up elsewhere, and we don't particularly want to show internals (as I said before), although we do. Steven indicated that he didn't have time to look into this, so we will need someone else.

[markusicu]

Looks good as far as I can tell.

What does? The "big open issue" from March 31 has not been resolved, has it?

[srl295]

@markusicu @sven-oly someone else want to take this over? or just close it?

[markusicu]

@sven-oly let's take another look at whether we still have the docs bug that triggered this.