[Bug libstdc++/97001] New: API documentation should have a minimum dialect

[Bug libstdc++/97001] New: API documentation should have a minimum dialect

[giecrilj at stegny dot 2a.pl]

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

            Bug ID: 97001
           Summary: API documentation should have a minimum dialect
           Product: gcc
           Version: 10.0
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: libstdc++
          Assignee: unassigned at gcc dot gnu.org
          Reporter: giecrilj at stegny dot 2a.pl
  Target Milestone: ---

For example, the documentation for std::cbegin[1] should say:
> Minimum dialect: c++14

___
[1] <URL:
https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01544.html#ac10e18b5c09f39bc07430a9d47e584a5
>

[Bug libstdc++/97001] API documentation should mention the minimum dialect

[redi at gcc dot gnu.org]

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

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

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |NEW
     Ever confirmed|0                           |1
   Last reconfirmed|                            |2020-09-09

--- Comment #1 from Jonathan Wakely <redi at gcc dot gnu.org> ---
And we should also build the docs with the latest dialect, so that everything
gets documented.

[Bug libstdc++/97001] API documentation should mention the minimum dialect

[cvs-commit at gcc dot gnu.org]

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

--- Comment #2 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:f2ce64b53fa76a4c192fe51b2f6c5a863a3b1241

commit r12-1964-gf2ce64b53fa76a4c192fe51b2f6c5a863a3b1241
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Jul 1 00:30:54 2021 +0100

    libstdc++: Improvements to Doxygen markup

    This attempst to improve the doxygen output to work around what seems to
    be some bugs in doxygen (issues 8635 and 8638).

    The @addtogroup command doesn't work for entities inside a nested
    namespace (see 8635) so we need to close and reopen groups on entering
    and elaving nested namespaces. This fixes the problem that
    chrono::duration and chrono::time_point were not documented in the
    "Time" documentation group. I am unable to make the path classes appear
    as part of their relevant groups (File System and Filesystem TS), nor
    the contents of <exception> or <system_error>. I have made some minor
    improvements to the docs for those types, including starting to address
    PR 97001 by adding @since to the doxygen comments.

    This change also excludes the <experimental/bits/net.h> header from
    Doxygen processing, so we don't get an unwanted "Networking-ts" group
    in the documentation.

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

    libstdc++-v3/ChangeLog:

            * doc/doxygen/doxygroups.cc: Fix docs for std::literals.
            * doc/doxygen/user.cfg.in: Exclude the Networking TS header.
            Add some more predefined macros.
            * include/bits/fs_fwd.h: Move @addtogroup commands inside
            namespaces. Add better documentation.
            * include/bits/fs_path.h: Likewise.
            * include/experimental/bits/fs_fwd.h: Likewise.
            * include/experimental/bits/fs_path.h: Likewise.
            * include/ext/throw_allocator.h: Fix typo and improve docs.
            * include/std/chrono: Move @addtogroup commands.
            * include/std/system_error: Move @addtogroup commands.
            * libsupc++/exception: Improve documentation.
            * libsupc++/exception.h: Add @since documentation.

[Bug libstdc++/97001] API documentation should mention the minimum dialect

[giecrilj at stegny dot 2a.pl]

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

--- Comment #3 from Christopher Yeleighton <giecrilj at stegny dot 2a.pl> ---
The problem with a module-level @since is that std:: symbols are easiest to
locate in the std namespace (which provides a huge index of everything).  Items
that are undocumented (there is a lot of them) in the namespace index are not
attributed to any module and the definition line is not available for them
either, so the reader needs a priori knowledge of which symbols belong to which
module.  While it is possible to guess the matching module with some
experience, just adding dummy documentation to those symbols (as a few of other
symbols have) would help navigating the API (also because the definition
sometimes is readable enough to be used instead of documentation).  Of course,
the fact that Doxygen bugs prevent some of the symbols from appearing in the
corresponding modules only adds to the general feeling of helplessness.

[Bug libstdc++/97001] API documentation should mention the minimum dialect

[redi at gcc dot gnu.org]

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

--- Comment #4 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Just use cppreference.com

[Bug libstdc++/97001] API documentation should mention the minimum dialect

[cvs-commit at gcc dot gnu.org]

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

--- Comment #5 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:ea32f15d44e4f50f3eb9deb3135e0b6d50f7ec43

commit r11-8846-gea32f15d44e4f50f3eb9deb3135e0b6d50f7ec43
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Jul 1 00:30:54 2021 +0100

    libstdc++: Improvements to Doxygen markup

    This attempts to improve the doxygen output to work around what seems to
    be some bugs in doxygen (issues 8635 and 8638).

    The @addtogroup command doesn't work for entities inside a nested
    namespace (see 8635) so we need to close and reopen groups on entering
    and elaving nested namespaces. This fixes the problem that
    chrono::duration and chrono::time_point were not documented in the
    "Time" documentation group. I am unable to make the path classes appear
    as part of their relevant groups (File System and Filesystem TS), nor
    the contents of <exception> or <system_error>. I have made some minor
    improvements to the docs for those types, including starting to address
    PR 97001 by adding @since to the doxygen comments.

    This change also excludes the <experimental/bits/net.h> header from
    Doxygen processing, so we don't get an unwanted "Networking-ts" group
    in the documentation.

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

    libstdc++-v3/ChangeLog:

            * doc/doxygen/doxygroups.cc: Fix docs for std::literals.
            * doc/doxygen/user.cfg.in: Exclude the Networking TS header.
            Add some more predefined macros.
            * include/bits/fs_fwd.h: Move @addtogroup commands inside
            namespaces. Add better documentation.
            * include/bits/fs_path.h: Likewise.
            * include/experimental/bits/fs_fwd.h: Likewise.
            * include/experimental/bits/fs_path.h: Likewise.
            * include/ext/throw_allocator.h: Fix typo and improve docs.
            * include/std/chrono: Move @addtogroup commands.
            * include/std/system_error: Move @addtogroup commands.
            * libsupc++/exception: Improve documentation.
            * libsupc++/exception.h: Add @since documentation.

    (cherry picked from commit f2ce64b53fa76a4c192fe51b2f6c5a863a3b1241)