Bug 97001 - API documentation should mention the minimum dialect
Summary: API documentation should mention the minimum dialect
Status: NEW
Alias: None
Product: gcc
Classification: Unclassified
Component: libstdc++ (show other bugs)
Version: 10.0
: P3 normal
Target Milestone: ---
Assignee: Not yet assigned to anyone
URL: https://gcc.gnu.org/onlinedocs/libstd...
Keywords: documentation
Depends on: 101268
Blocks:
  Show dependency treegraph
 
Reported: 2020-09-09 15:20 UTC by Christopher Yeleighton
Modified: 2021-08-11 15:42 UTC (History)
1 user (show)

See Also:
Host:
Target:
Build:
Known to work:
Known to fail:
Last reconfirmed: 2020-09-09 00:00:00


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Christopher Yeleighton 2020-09-09 15:20:13 UTC
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 >
Comment 1 Jonathan Wakely 2020-09-09 15:39:16 UTC
And we should also build the docs with the latest dialect, so that everything gets documented.
Comment 2 CVS Commits 2021-07-01 18:24:37 UTC
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.
Comment 3 Christopher Yeleighton 2021-07-03 15:55:13 UTC
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.
Comment 4 Jonathan Wakely 2021-07-03 19:44:14 UTC
Just use cppreference.com
Comment 5 CVS Commits 2021-08-11 15:42:34 UTC
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)