[libcxx-commits] [PATCH] D129310: [libc++][doc] Documents the header __bits.

[Louis Dionne via Phabricator via libcxx-commits]

ldionne requested changes to this revision.
ldionne added inline comments.
This revision now requires changes to proceed.


================
Comment at: libcxx/docs/UsingLibcxx.rst:434
+
+Compiler intrinsics wrappers
+----------------------------
----------------
My comment in https://reviews.llvm.org/D128929#inline-1241329 was asking to document the fact that `__uint128_t` can be used with *public* functions in `<bits>` (and also in a few other places like `<random>`, `<charconv>`, `<type_traits>`, etc). I don't think we should document internal-only functions and headers, since this is asking for trouble when users start depending on them.

I'm sorry if my comment in the other review was not clear enough.


================
Comment at: libcxx/docs/UsingLibcxx.rst:447-448
+
+Starting with C++20 the Standard header ``<bit>`` is available. This header
+contains all functions available in  ``<__bits>``` under a different name.
+
----------------
Mordante wrote:
> philnik wrote:
> > Mordante wrote:
> > > philnik wrote:
> > > > Could you maybe add a TODO somewhere to update the function names to match the standard ones?
> > > I'm not sure whether we want to update these names. On one hand it's nice to use the C++20 name on the other hand I like to use the intrinsic's name. But I have no strong preference in either direction.
> > > @lidonne What's your preference?
> > > 
> > > I'm not going to add a TODO. If we want to use the C++20 names I'll do the renaming in a separate patch as a parent of this one and adjust this one to the new names.
> > Normally we mirror the names of the standard ones. This makes a lot of sense IMO, since people are much more likely to be familiar with the standard names than with intrinsics. Personally I also find the names `countl_zero` and `countr_zero` a lot more intuitive than `ctz` and `clz`. Unless you already know that `ctz` is count trailing zeros you would never guess that.
> I don't object, but let's agree on the rename before doing the work.
> (In this case I think the Standard library names aren't great either ;-) countr looks like a typo of counter.)
I'm mostly neutral on this, but I guess it would be more consistent to name them after their standardized names. However, note that this is only beneficial for libc++ developers themselves, since we never expect users to use these names.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D129310/new/

https://reviews.llvm.org/D129310