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 >
And we should also build the docs with the latest dialect, so that everything gets documented.
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.
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.
Just use cppreference.com
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)