Where is the documentation for icu::NumberFormatter?

Description

There's either precious little online documentation for the new NumberFormatter framework, or it's there and I just can't find it in what I thought were the obvious places.

When I try to find the API documentation by clicking on the "ICU4C" link under "API References" on the main ICU page and then clicking on "icu::number::NumberFormatter" on the index page that comes up, I get a Doxygen page for the NumberFormatter class itself, which contains four methods and virtually no overview documentation on either that class or the whole framework. There's a link at the top of the page saying I should look at the main documentation comment in numberformatter.h. That comment gives a little bit of context and some helpful examples, but is far from comprehensive and doesn't point to any pages where one can go to get more detailed or comprehensive reference info. The one thing it does point to is the design doc, which does more or less give me what I'm looking for, but it's out of date-- the actual API of the NumberFormatter framework doesn't exactly match what is described in the design doc.

If I try alternative approaches to get more comprehensive info from the API-reference page, I don't get anywhere either-- if I click on the "Namespace" tab, the only namespace I get is "icu", and the "number" namespace it wraps isn't listed on that page. The "Modules" page doesn't seem to have anything at all. The "Data Structures" tab gives me a list of classes at the root level, plus the "icu" namespace. Clicking on "icu" takes me back to the "icu" namespace page, which didn't seem to have any of the NumberFormatter stuff in it (and the disclosure triangle next to "icu" didn't do anything). The icu::number stuff is listed in the "Class Hierarchy" page, but it's hard to tell where to look for a particular individual class-- the things at the top level of that namespace don't seem to have a clear hierarchy or relationship to one another. The individual files are all listed on the "Files" tab, but again you have to know where to look-- it's not helpful if you're coming to the new framework cold.

If I click on "User Guide" on the main page and then on "Formatting Numbers" in the sidebar, I get a page with the old NumberFormat API's documentation grayed out and a message at the top pointing to the new NumberFormatter and NumberRangeFormatter documentation. But if I click on either link, I'm instead taken to the top level of the ICU4J API reference page, not to anything relating to NumberFormatter (I assume the links are dead and it's falling back to the top level). If I just go to the NumberFormatter page in the ICU4J API reference, I get more or less the same thing I got in the numberformatter.h page in the ICU4C API reference, and that's not enough to get me started if I'm coming to this cold.

I'm guessing what I'm seeing is partially a result of limitations in Doxygen and partially because updates to the user's guide are being held up by the conversion to Markdown, but other than the original design doc and the actual header files, I'm not sure how a new user coming to ICU cold would be expected to figure out how to use the new code.

Assignee

Shane Carr

Reporter

Rich Gillam

Components

Labels

None

Reviewer

Rich Gillam

Priority

major

Time Needed

Hours

Fix versions

Configure