ICU-13685 c: add @preview (retry)

[srl295]

ICU-13685

re-open from #7

Tech Preview should not be 'do not use', but @internal in Doxygen comes with an ominous warning.

Add @preview as a doxygen command such that:

@preview ICU 4.4

gives:

[jefgen]

FWIW, LGTM.

[sffc]

How does this work with the U_HIDE_INTERNAL_API flags? Do we apply that to both @internal and @preview, or do we make a new flag like U_HIDE_PREVIEW_API?

[jefgen]

I think most (all?) of these are already behind #ifndef U_HIDE_INTERNAL_API conditions, but I wonder if a
#ifndef U_HIDE_PREVIEW_API might be more clear?

[srl295]

@jefgen these should already be behind hide internal API. If we want a hide preview API we should probably do that separately.

[srl295]

okay, conflicts with #29 now

[srl295]

@sffc actually, i would kind of be inclined to change preview to be behind U_DRAFT and U_HIDE_DRAFT_API — because really, it is more of a draft API than internal.

but i could see the argument for a separate U_PREVIEW and U_HIDE_PREVIEW_API (which defaults to being controlled by U_HIDE_DRAFT_API) - what do you think?

[sffc]

The real difference between @draft and @preview is that the latter does not need to go through as formal of a review process. I've put APIs in both buckets, and I treat changes to @draft much more carefully than @preview. For example, when I changed the name "Rounder" to "Precision" in 62.1, I added a backwards-compatibility API to allow people to transition to the new name; if the API had been @preview instead of @draft, I would have probably wouldn't have gone through that extra step.

In other words, in terms of stability, I see:

• @stable is the most stable; we do our best to guarantee that users' code won't break if they use this API.
• @draft is mostly stable but still subject to some changes with sufficient advance notice and migration paths. Early adopters are welcome and encouraged to use it, and we go out of our way to make their lives easier if we ever decide to change the API. You could call it "beta-quality".
• @preview makes no claims about API stability, but users can have a certain expectation for what the behavior should be. Early adopters are taking a risk when they use it; they are on their own if we decide to change the API. You could call it "alpha-quality".
• @internal makes no claims about either API or behavior stability; users should never call these APIs in their own code unless they are ICU or CLDR.

I would like to see different flags for all three non-@stable levels. @draft should default to on, and @internal should default to off. We can debate whether we want @preview to default to on or off.

[srl295]

@sffc so given your comment, perhaps this PR (as is) is a good step forward - @preview is no more visible than @internal, is still behind U_HIDE_INTERNAL_API. This only improves documentation and makes no change to the visibility of anything.

[sffc]

SGTM; the new flag U_HIDE_PREVIEW_API can be added in a follow-up.

[srl295]

@sffc @jefgen i have 'verbal' feedback from you both, please review