I was reading the documentation for unique_ptr: http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00587.html This mentions unique_ptr.h -- but that is not a user-allowed header file. Instead the user ought to write "#include <memory>". This is not mentioned anywhere, but IMO it should be.
Agreed. Thanks for the feedback on docs. Will put this on the docs todo list.
Add documentation keyword
Just an update on this. From 4.6.0 onward, the file documentation for things like bits/unique_ptr.h now have forwarding text: http://gcc.gnu.org/onlinedocs/libstdc++/libstdc++-api-4.6/a01102.html " Detailed Description This is an internal header file, included by other library headers. Do not attempt to use it directly. Instead, include <memory>. Definition in file unique_ptr.h. " I think this is useful, but not as useful as saying that to use std::unique_ptr one needs to include <memory>.
Busg like this make me wonder if we wouldn't be better simply replacing our Doxygen API docs with a link to cppreference.com which is far more complete and has better formatting and cross referencing.
If we do this for each class: @class unique_ptr memory and enable SHOW_INCLUDE_FILES=YES in the doxygen config, then we get this in the docs for unique_ptr: #include <memory> It also seems to avoid the doxygen bug that causes @ingroup or @addtogroup to be ignored for classes. The downside is that SHOW_INCLUDE_FILES=YES also causes the docs for each file to show a full list of all headers it includes: #include <bits/c++config.h> #include <bits/exception.h> #include <bits/exception_ptr.h> #include <bits/nested_exception.h> I don't think we want to show those internal headers in the public API docs, so I've asked for a way to avoid that: https://github.com/doxygen/doxygen/issues/8639
My doxygen patch was merged, so we can start to use SHOW_HEADERFILE and @headerfile to do this.
The master branch has been updated by Jonathan Wakely <redi@gcc.gnu.org>: https://gcc.gnu.org/g:865869dc6943eb5dee855bc1ea88b09b7dabc641 commit r14-290-g865869dc6943eb5dee855bc1ea88b09b7dabc641 Author: Jonathan Wakely <jwakely@redhat.com> Date: Wed Apr 26 22:48:35 2023 +0100 libstdc++: Add @headerfile and @since to doxygen comments [PR40380] libstdc++-v3/ChangeLog: PR libstdc++/40380 * include/bits/basic_string.h: Improve doxygen comments. * include/bits/cow_string.h: Likewise. * include/bits/forward_list.h: Likewise. * include/bits/fs_dir.h: Likewise. * include/bits/fs_path.h: Likewise. * include/bits/quoted_string.h: Likewise. * include/bits/stl_bvector.h: Likewise. * include/bits/stl_map.h: Likewise. * include/bits/stl_multimap.h: Likewise. * include/bits/stl_multiset.h: Likewise. * include/bits/stl_set.h: Likewise. * include/bits/stl_vector.h: Likewise. * include/bits/unordered_map.h: Likewise. * include/bits/unordered_set.h: Likewise. * include/std/filesystem: Likewise. * include/std/iomanip: Likewise.
Added some more of these @headerfile annotations, but there's still more to do.
Grr, I've just noticed that classes defined in a header with no file extension do not get an implicit @headerfile, the way that classes defined in a foo.h header do. See https://github.com/doxygen/doxygen/issues/10010 This is frustrating for libstdc++, because **none** of the public headers have an extension, so we can't rely on all the contents of e.g. <memory_resource> getting a correct #include <memory_resource> displayed. The _only_ classes which show a #include are the ones in a .h file where it's always wrong (until we add an explicit @headerfile to them). So unless that doxygen issue gets fixed, we need an explicit @headerfile on every single class in the library. Sigh.
The releases/gcc-13 branch has been updated by Jonathan Wakely <redi@gcc.gnu.org>: https://gcc.gnu.org/g:7bd8a81f39e084d43c6701afb6203510b5fe69a2 commit r13-7264-g7bd8a81f39e084d43c6701afb6203510b5fe69a2 Author: Jonathan Wakely <jwakely@redhat.com> Date: Wed Apr 26 22:48:35 2023 +0100 libstdc++: Add @headerfile and @since to doxygen comments [PR40380] libstdc++-v3/ChangeLog: PR libstdc++/40380 * include/bits/basic_string.h: Improve doxygen comments. * include/bits/cow_string.h: Likewise. * include/bits/forward_list.h: Likewise. * include/bits/fs_dir.h: Likewise. * include/bits/fs_path.h: Likewise. * include/bits/quoted_string.h: Likewise. * include/bits/stl_bvector.h: Likewise. * include/bits/stl_map.h: Likewise. * include/bits/stl_multimap.h: Likewise. * include/bits/stl_multiset.h: Likewise. * include/bits/stl_set.h: Likewise. * include/bits/stl_vector.h: Likewise. * include/bits/unordered_map.h: Likewise. * include/bits/unordered_set.h: Likewise. * include/std/filesystem: Likewise. * include/std/iomanip: Likewise. (cherry picked from commit 865869dc6943eb5dee855bc1ea88b09b7dabc641)
Unassigning since Benjamin since not been active in GCC development for over 8 years now.
The releases/gcc-12 branch has been updated by Jonathan Wakely <redi@gcc.gnu.org>: https://gcc.gnu.org/g:afefe951acd8bae13be0e1b700262316254ce935 commit r12-10278-gafefe951acd8bae13be0e1b700262316254ce935 Author: Jonathan Wakely <jwakely@redhat.com> Date: Wed Apr 26 22:48:35 2023 +0100 libstdc++: Add @headerfile and @since to doxygen comments [PR40380] libstdc++-v3/ChangeLog: PR libstdc++/40380 * include/bits/basic_string.h: Improve doxygen comments. * include/bits/cow_string.h: Likewise. * include/bits/forward_list.h: Likewise. * include/bits/fs_dir.h: Likewise. * include/bits/fs_path.h: Likewise. * include/bits/quoted_string.h: Likewise. * include/bits/stl_bvector.h: Likewise. * include/bits/stl_map.h: Likewise. * include/bits/stl_multimap.h: Likewise. * include/bits/stl_multiset.h: Likewise. * include/bits/stl_set.h: Likewise. * include/bits/stl_vector.h: Likewise. * include/bits/unordered_map.h: Likewise. * include/bits/unordered_set.h: Likewise. * include/std/filesystem: Likewise. * include/std/iomanip: Likewise. (cherry picked from commit 865869dc6943eb5dee855bc1ea88b09b7dabc641)