[Bug libstdc++/101258] New: std ::is_integral_v is undocumented

[Bug libstdc++/101258] New: std ::is_integral_v is undocumented

[giecrilj at stegny dot 2a.pl]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

            Bug ID: 101258
           Summary: std ::is_integral_v is undocumented
           Product: gcc
           Version: unknown
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: libstdc++
          Assignee: unassigned at gcc dot gnu.org
          Reporter: giecrilj at stegny dot 2a.pl
  Target Milestone: ---

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #1 from Jonathan Wakely <redi at gcc dot gnu.org> ---
It does exactly what the standard says it does. And it's self explanatory.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |documentation

--- Comment #2 from Jonathan Wakely <redi at gcc dot gnu.org> ---
https://en.cppreference.com/w/cpp/types#Type_traits
https://en.cppreference.com/w/cpp/types/is_integral

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[giecrilj at stegny dot 2a.pl]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #3 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> ---
It should at least be present on the API page.  The standard is not for
developers.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[giecrilj at stegny dot 2a.pl]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #4 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> ---
(In reply to Jonathan Wakely from comment #1)
> It does exactly what the standard says it does. And it's self explanatory.

What is self-explanatory in is_integral_v?  It could be "is integral verbose"
or "is integral equal to Roman numeral v" or "is integral virtually" or
anything else.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|---                         |WONTFIX
             Status|UNCONFIRMED                 |RESOLVED

--- Comment #5 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Christopher Yeleighton from comment #3)
> It should at least be present on the API page.  The standard is not for
> developers.

cppreference.com is not the standard, it's a reference for developers.

(In reply to Christopher Yeleighton from comment #4)
> What is self-explanatory in is_integral_v?

If you don't know what the xxx_v variables in <type_traits> do, you should get
a good (modern) tutorial on C++.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #6 from Jonathan Wakely <redi at gcc dot gnu.org> ---
While it would be nice if the libstdc++ API docs were 100% complete and
described every piece of the library, that is never going to happen. If you are
trying to use those docs to learn C++ you should stop, and look elsewhere.

The API of libstdc++ is what is described in the standard, and cppreference.com
does a better job of documenting it than we ever will.

So unless we suddenly run out of new features to implement and bugs to fix, I
don't think anybody is going to add documentation for everything like that.

I have regenerated the latest-doxygen docs to include C++17 features:
https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html
No is_integral_v is listed (with no description) at:
https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01625.html#a824c5eb1a7e8aafa382dc9af3329a9e8

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[giecrilj at stegny dot 2a.pl]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #7 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> ---
(In reply to Jonathan Wakely from comment #5)
> (In reply to Christopher Yeleighton from comment #3)
> > It should at least be present on the API page.  The standard is not for
> > developers.
> 
> cppreference.com is not the standard, it's a reference for developers.
> 
> (In reply to Christopher Yeleighton from comment #4)
> > What is self-explanatory in is_integral_v?
> 
> If you don't know what the xxx_v variables in <type_traits> do, you should
> get a good (modern) tutorial on C++.

"Self-explanatory" implies that no tutorial is needed.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[giecrilj at stegny dot 2a.pl]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #8 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> ---
(In reply to Jonathan Wakely from comment #6)
> While it would be nice if the libstdc++ API docs were 100% complete and
> described every piece of the library, that is never going to happen. If you
> are trying to use those docs to learn C++ you should stop, and look
> elsewhere.

I am trying to read somebody else’s code and that developer is using things
that I would never use and I think should never make it to the standard in the
first place.  The ugliness of these things compares only with sbumpc.  So I
wanted to check whether this is a standard thing he used---and the reply from
the API doc was negative.  Thank you for making this problem a bit less
painful.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #9 from Jonathan Wakely <redi at gcc dot gnu.org> ---
(In reply to Christopher Yeleighton from comment #8)
> reply from the API doc was negative.

Stop trying to use it to check what is in the standard. It's not meant for
that.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #10 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Lots of things in our API docs are not in the standard, and lots of things in
the standard are not in our API docs. If you're trying to use it for that, no
wonder it's painful. Stop it.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[pinskia at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #11 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Note the v in is_integral_v stands for value :).

GCC's job is also not to teach you C++, though the documentation and warnings
can help.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[giecrilj at stegny dot 2a.pl]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #12 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> ---
(In reply to Jonathan Wakely from comment #10)
> Lots of things in our API docs are not in the standard, and lots of things
> in the standard are not in our API docs. If you're trying to use it for
> that, no wonder it's painful. Stop it.

The difference between compiler documentation and the standard is that compiler
documentation is easier to use and to understand and more task-oriented,
although it may be incomplete.  I understand the difference.  I understand that
compiler documentation may sacrifice precision for clarity here and there.  The
sacrifice must not go too far though---hence my patches to MSDN for example.  I
still prefer reading the vendor documentation to reading the standard, except
in some special cases.

I promise I shall stop using GCC documentation if said documentation tells me
what I should use instead.  I have reported a request regarding that.  I can
still hardly accept that we are such a failure in this area (I believe that if
we have time to implement things, we should also dedicate some to describe
them).

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #13 from Jonathan Wakely <redi at gcc dot gnu.org> ---
I never said to read the standard though. I said to use cppreference.com

I repeat, cppreference.com is not the standard. What you are looking for is
cppreference.com.

(In reply to Christopher Yeleighton from comment #12)
> can still hardly accept that we are such a failure in this area (I believe
> that if we have time to implement things, we should also dedicate some to
> describe them).

Why don't you contribute improvements then?

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[giecrilj at stegny dot 2a.pl]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #14 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> ---
Will you accept an improvement regarding an issue RESOLVED WONTFIX?

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #15 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Yes, what I said was:

(In reply to Jonathan Wakely from comment #6)
> So unless we suddenly run out of new features to implement and bugs to fix,
> I don't think anybody is going to add documentation for everything like that.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #16 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The master branch has been updated by Jonathan Wakely <redi@gcc.gnu.org>:

https://gcc.gnu.org/g:6963c3b9ed1308bf5d2d8877956e56fec92853a7

commit r12-1943-g6963c3b9ed1308bf5d2d8877956e56fec92853a7
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Wed Jun 30 16:00:58 2021 +0100

    libstdc++: Improve Doxygen documentation groups [PR 101258]

    This defines some new Doxygen groups for C++17 variable templates and
    for the contents of <experimental/type_traits>. By documenting the group
    as a whole and adding each template to a group we don't need to document
    them individually.

    Also mark more internals with "@cond undocumented" so that Doxygen
    ignores them by default. Also make Doxygen process <experimental/simd>.

    For some reason, many of the class templates in <type_traits> do not
    appear in the "Metaprogramming" group. For example, add_cv,
    remove_extent, and all the is_xxx_constructible and is_xxx_assignable
    traits. For some reason, Doxygen doesn't include them in the group,
    despite doing it correctly for other traits in the same header.

    Signed-off-by: Jonathan Wakely <jwakely@redhat.com>

    libstdc++-v3/ChangeLog:

            PR libstdc++/101258
            * doc/doxygen/user.cfg.in (INPUT): Add <experimental/simd>.
            (COLS_IN_ALPHA_INDEX): Remove obsolete tag.
            (PREDEFINED): Add/fix some more macros that need to be expanded.
            * include/bits/random.h: Stop Doxygen from documenting internal
            implementation details.
            * include/bits/random.tcc: Likewise.
            * include/bits/this_thread_sleep.h: Fix @file name.
            * include/experimental/bits/simd.h: Add to Doxygen group. Do not
            document internal implementation details.
            * include/experimental/bits/simd_detail.h: Do not document
            internal implementation details.
            * include/experimental/simd: Define Doxygen groups.
            * include/experimental/type_traits: Improve documentation for
            the header file. Define groups. Use @since commands.
            * include/std/scoped_allocator (scoped_allocator_adaptor): Move
            declaration before undocumented region.
            * include/std/type_traits (true_type, false_type): Use using
            declaration instead of typedef.
            (is_invocable_v, is_nothrow_invocable_v, is_invocable_r_v)
            (is_nothrow_invocable_r_v): Move definitions next to other C++17
            variable templates.
            Do not document internal implementation details. Move misplaced
            group-end command. Define group for variable templates.
            * include/std/variant: Do not document internal implementation
            details.
            * testsuite/26_numerics/random/pr60037-neg.cc: Adjust dg-error
            line number.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|WONTFIX                     |FIXED

--- Comment #17 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Fixed now anyway

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #18 from Jonathan Wakely <redi at gcc dot gnu.org> ---
The main problem with trying to rely on doxygen is that it's very buggy and
simply refuses to generate good docs for some entities, even though they are
correctly documented. See the commit message above, and see
https://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-api.20210701.html/a01556.html
where it refuses to put filesystem::path in the relevant module despite
@ingroup being used.

And https://github.com/doxygen/doxygen/issues/8633 causes some entities to be
undocumented, because doxygen can't parse whitespace between tokens.

Obviously nobody is going to create something better than doxygen just for
libstdc++, so it's the best option we have.

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

--- Comment #19 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The releases/gcc-11 branch has been updated by Jonathan Wakely
<redi@gcc.gnu.org>:

https://gcc.gnu.org/g:63758bead0337b5225016711bf9d540cf7cc80b1

commit r11-8845-g63758bead0337b5225016711bf9d540cf7cc80b1
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Wed Jun 30 16:00:58 2021 +0100

    libstdc++: Improve Doxygen documentation groups [PR 101258]

    This defines some new Doxygen groups for C++17 variable templates and
    for the contents of <experimental/type_traits>. By documenting the group
    as a whole and adding each template to a group we don't need to document
    them individually.

    Also mark more internals with "@cond undocumented" so that Doxygen
    ignores them by default. Also make Doxygen process <experimental/simd>.

    For some reason, many of the class templates in <type_traits> do not
    appear in the "Metaprogramming" group. For example, add_cv,
    remove_extent, and all the is_xxx_constructible and is_xxx_assignable
    traits. For some reason, Doxygen doesn't include them in the group,
    despite doing it correctly for other traits in the same header.

    Signed-off-by: Jonathan Wakely <jwakely@redhat.com>

    libstdc++-v3/ChangeLog:

            PR libstdc++/101258
            * doc/doxygen/user.cfg.in (INPUT): Add <experimental/simd>.
            (COLS_IN_ALPHA_INDEX): Remove obsolete tag.
            (PREDEFINED): Add/fix some more macros that need to be expanded.
            * include/bits/random.h: Stop Doxygen from documenting internal
            implementation details.
            * include/bits/random.tcc: Likewise.
            * include/bits/this_thread_sleep.h: Fix @file name.
            * include/experimental/bits/simd.h: Add to Doxygen group. Do not
            document internal implementation details.
            * include/experimental/bits/simd_detail.h: Do not document
            internal implementation details.
            * include/experimental/simd: Define Doxygen groups.
            * include/experimental/type_traits: Improve documentation for
            the header file. Define groups. Use @since commands.
            * include/std/scoped_allocator (scoped_allocator_adaptor): Move
            declaration before undocumented region.
            * include/std/type_traits (true_type, false_type): Use using
            declaration instead of typedef.
            (is_invocable_v, is_nothrow_invocable_v, is_invocable_r_v)
            (is_nothrow_invocable_r_v): Move definitions next to other C++17
            variable templates.
            Do not document internal implementation details. Move misplaced
            group-end command. Define group for variable templates.
            * include/std/variant: Do not document internal implementation
            details.
            * testsuite/26_numerics/random/pr60037-neg.cc: Adjust dg-error
            line number.

    (cherry picked from commit 6963c3b9ed1308bf5d2d8877956e56fec92853a7)

[Bug libstdc++/101258] std ::is_integral_v is undocumented

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=101258

Jonathan Wakely <redi at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
   Target Milestone|---                         |11.3