public inbox for gcc-bugs@sourceware.org
help / color / mirror / Atom feed
* [Bug libstdc++/97001] New: API documentation should have a minimum dialect
@ 2020-09-09 15:20 giecrilj at stegny dot 2a.pl
2020-09-09 15:39 ` [Bug libstdc++/97001] API documentation should mention the " redi at gcc dot gnu.org
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: giecrilj at stegny dot 2a.pl @ 2020-09-09 15:20 UTC (permalink / raw)
To: gcc-bugs
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
>
^ permalink raw reply [flat|nested] 6+ messages in thread* [Bug libstdc++/97001] API documentation should mention the minimum dialect
2020-09-09 15:20 [Bug libstdc++/97001] New: API documentation should have a minimum dialect giecrilj at stegny dot 2a.pl
@ 2020-09-09 15:39 ` redi at gcc dot gnu.org
2021-07-01 18:24 ` cvs-commit at gcc dot gnu.org
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: redi at gcc dot gnu.org @ 2020-09-09 15:39 UTC (permalink / raw)
To: gcc-bugs
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.
^ permalink raw reply [flat|nested] 6+ messages in thread* [Bug libstdc++/97001] API documentation should mention the minimum dialect
2020-09-09 15:20 [Bug libstdc++/97001] New: API documentation should have a minimum dialect giecrilj at stegny dot 2a.pl
2020-09-09 15:39 ` [Bug libstdc++/97001] API documentation should mention the " redi at gcc dot gnu.org
@ 2021-07-01 18:24 ` cvs-commit at gcc dot gnu.org
2021-07-03 15:55 ` giecrilj at stegny dot 2a.pl
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: cvs-commit at gcc dot gnu.org @ 2021-07-01 18:24 UTC (permalink / raw)
To: gcc-bugs
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.
^ permalink raw reply [flat|nested] 6+ messages in thread* [Bug libstdc++/97001] API documentation should mention the minimum dialect
2020-09-09 15:20 [Bug libstdc++/97001] New: API documentation should have a minimum dialect giecrilj at stegny dot 2a.pl
2020-09-09 15:39 ` [Bug libstdc++/97001] API documentation should mention the " redi at gcc dot gnu.org
2021-07-01 18:24 ` cvs-commit at gcc dot gnu.org
@ 2021-07-03 15:55 ` giecrilj at stegny dot 2a.pl
2021-07-03 19:44 ` redi at gcc dot gnu.org
2021-08-11 15:42 ` cvs-commit at gcc dot gnu.org
4 siblings, 0 replies; 6+ messages in thread
From: giecrilj at stegny dot 2a.pl @ 2021-07-03 15:55 UTC (permalink / raw)
To: gcc-bugs
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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* [Bug libstdc++/97001] API documentation should mention the minimum dialect
2020-09-09 15:20 [Bug libstdc++/97001] New: API documentation should have a minimum dialect giecrilj at stegny dot 2a.pl
` (2 preceding siblings ...)
2021-07-03 15:55 ` giecrilj at stegny dot 2a.pl
@ 2021-07-03 19:44 ` redi at gcc dot gnu.org
2021-08-11 15:42 ` cvs-commit at gcc dot gnu.org
4 siblings, 0 replies; 6+ messages in thread
From: redi at gcc dot gnu.org @ 2021-07-03 19:44 UTC (permalink / raw)
To: gcc-bugs
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
^ permalink raw reply [flat|nested] 6+ messages in thread* [Bug libstdc++/97001] API documentation should mention the minimum dialect
2020-09-09 15:20 [Bug libstdc++/97001] New: API documentation should have a minimum dialect giecrilj at stegny dot 2a.pl
` (3 preceding siblings ...)
2021-07-03 19:44 ` redi at gcc dot gnu.org
@ 2021-08-11 15:42 ` cvs-commit at gcc dot gnu.org
4 siblings, 0 replies; 6+ messages in thread
From: cvs-commit at gcc dot gnu.org @ 2021-08-11 15:42 UTC (permalink / raw)
To: gcc-bugs
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)
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2021-08-11 15:42 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-09 15:20 [Bug libstdc++/97001] New: API documentation should have a minimum dialect giecrilj at stegny dot 2a.pl
2020-09-09 15:39 ` [Bug libstdc++/97001] API documentation should mention the " redi at gcc dot gnu.org
2021-07-01 18:24 ` cvs-commit at gcc dot gnu.org
2021-07-03 15:55 ` giecrilj at stegny dot 2a.pl
2021-07-03 19:44 ` redi at gcc dot gnu.org
2021-08-11 15:42 ` cvs-commit at gcc dot gnu.org
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).