[Bug libstdc++/40380] New: class documentation should mention include file to use

public inbox for gcc-bugs@sourceware.org
help / color / mirror / Atom feed

* [Bug libstdc++/40380]  New: class documentation should mention include file to use
@ 2009-06-08 21:36 tromey at gcc dot gnu dot org
  2009-06-18  0:00 ` [Bug libstdc++/40380] " bkoz at gcc dot gnu dot org
  2009-06-18  0:34 ` bkoz at gcc dot gnu dot org
  0 siblings, 2 replies; 12+ messages in thread
From: tromey at gcc dot gnu dot org @ 2009-06-08 21:36 UTC (permalink / raw)
  To: gcc-bugs

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.


-- 
           Summary: class documentation should mention include file to use
           Product: gcc
           Version: 4.5.0
            Status: UNCONFIRMED
          Severity: enhancement
          Priority: P3
         Component: libstdc++
        AssignedTo: unassigned at gcc dot gnu dot org
        ReportedBy: tromey at gcc dot gnu dot org


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=40380


^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
  2009-06-08 21:36 [Bug libstdc++/40380] New: class documentation should mention include file to use tromey at gcc dot gnu dot org
@ 2009-06-18  0:00 ` bkoz at gcc dot gnu dot org
  2009-06-18  0:34 ` bkoz at gcc dot gnu dot org
  1 sibling, 0 replies; 12+ messages in thread
From: bkoz at gcc dot gnu dot org @ 2009-06-18  0:00 UTC (permalink / raw)
  To: gcc-bugs



------- Comment #1 from bkoz at gcc dot gnu dot org  2009-06-18 00:00 -------

Agreed. Thanks for the feedback on docs. Will put this on the docs todo list.


-- 


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=40380


^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
  2009-06-08 21:36 [Bug libstdc++/40380] New: class documentation should mention include file to use tromey at gcc dot gnu dot org
  2009-06-18  0:00 ` [Bug libstdc++/40380] " bkoz at gcc dot gnu dot org
@ 2009-06-18  0:34 ` bkoz at gcc dot gnu dot org
  1 sibling, 0 replies; 12+ messages in thread
From: bkoz at gcc dot gnu dot org @ 2009-06-18  0:34 UTC (permalink / raw)
  To: gcc-bugs



------- Comment #2 from bkoz at gcc dot gnu dot org  2009-06-18 00:34 -------
Add documentation keyword


-- 

bkoz at gcc dot gnu dot org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |documentation


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=40380


^ permalink raw reply	[flat|nested] 12+ messages in thread

[parent not found: <bug-40380-4@http.gcc.gnu.org/bugzilla/>]

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
@ 2012-05-02 22:58 ` bkoz at gcc dot gnu.org
  2021-07-01 20:11 ` redi at gcc dot gnu.org
                   ` (7 subsequent siblings)
  8 siblings, 0 replies; 12+ messages in thread
From: bkoz at gcc dot gnu.org @ 2012-05-02 22:58 UTC (permalink / raw)
  To: gcc-bugs

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=40380

Benjamin Kosnik <bkoz at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |ASSIGNED
   Last reconfirmed|                            |2012-05-02
                 CC|                            |bkoz at gcc dot gnu.org
         AssignedTo|unassigned at gcc dot       |bkoz at gcc dot gnu.org
                   |gnu.org                     |
     Ever Confirmed|0                           |1

--- Comment #3 from Benjamin Kosnik <bkoz at gcc dot gnu.org> 2012-05-02 22:56:37 UTC ---

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>.


^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
  2012-05-02 22:58 ` bkoz at gcc dot gnu.org
@ 2021-07-01 20:11 ` redi at gcc dot gnu.org
  2021-07-21 18:52 ` redi at gcc dot gnu.org
                   ` (6 subsequent siblings)
  8 siblings, 0 replies; 12+ messages in thread
From: redi at gcc dot gnu.org @ 2021-07-01 20:11 UTC (permalink / raw)
  To: gcc-bugs

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

--- Comment #5 from Jonathan Wakely <redi at gcc dot gnu.org> ---
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

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
  2012-05-02 22:58 ` bkoz at gcc dot gnu.org
  2021-07-01 20:11 ` redi at gcc dot gnu.org
@ 2021-07-21 18:52 ` redi at gcc dot gnu.org
  2023-04-27 10:29 ` cvs-commit at gcc dot gnu.org
                   ` (5 subsequent siblings)
  8 siblings, 0 replies; 12+ messages in thread
From: redi at gcc dot gnu.org @ 2021-07-21 18:52 UTC (permalink / raw)
  To: gcc-bugs

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

--- Comment #6 from Jonathan Wakely <redi at gcc dot gnu.org> ---
My doxygen patch was merged, so we can start to use SHOW_HEADERFILE and
@headerfile to do this.

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
                   ` (2 preceding siblings ...)
  2021-07-21 18:52 ` redi at gcc dot gnu.org
@ 2023-04-27 10:29 ` cvs-commit at gcc dot gnu.org
  2023-04-27 10:42 ` redi at gcc dot gnu.org
                   ` (4 subsequent siblings)
  8 siblings, 0 replies; 12+ messages in thread
From: cvs-commit at gcc dot gnu.org @ 2023-04-27 10:29 UTC (permalink / raw)
  To: gcc-bugs

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

--- Comment #7 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: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.

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
                   ` (3 preceding siblings ...)
  2023-04-27 10:29 ` cvs-commit at gcc dot gnu.org
@ 2023-04-27 10:42 ` redi at gcc dot gnu.org
  2023-04-27 16:00 ` redi at gcc dot gnu.org
                   ` (3 subsequent siblings)
  8 siblings, 0 replies; 12+ messages in thread
From: redi at gcc dot gnu.org @ 2023-04-27 10:42 UTC (permalink / raw)
  To: gcc-bugs

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

--- Comment #8 from Jonathan Wakely <redi at gcc dot gnu.org> ---
Added some more of these @headerfile annotations, but there's still more to do.

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
                   ` (4 preceding siblings ...)
  2023-04-27 10:42 ` redi at gcc dot gnu.org
@ 2023-04-27 16:00 ` redi at gcc dot gnu.org
  2023-04-28 13:10 ` cvs-commit at gcc dot gnu.org
                   ` (2 subsequent siblings)
  8 siblings, 0 replies; 12+ messages in thread
From: redi at gcc dot gnu.org @ 2023-04-27 16:00 UTC (permalink / raw)
  To: gcc-bugs

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

--- Comment #9 from Jonathan Wakely <redi at gcc dot gnu.org> ---
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.

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
                   ` (5 preceding siblings ...)
  2023-04-27 16:00 ` redi at gcc dot gnu.org
@ 2023-04-28 13:10 ` cvs-commit at gcc dot gnu.org
  2023-05-16 19:41 ` pinskia at gcc dot gnu.org
  2024-03-18 14:08 ` cvs-commit at gcc dot gnu.org
  8 siblings, 0 replies; 12+ messages in thread
From: cvs-commit at gcc dot gnu.org @ 2023-04-28 13:10 UTC (permalink / raw)
  To: gcc-bugs

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

--- Comment #10 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
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)

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
                   ` (6 preceding siblings ...)
  2023-04-28 13:10 ` cvs-commit at gcc dot gnu.org
@ 2023-05-16 19:41 ` pinskia at gcc dot gnu.org
  2024-03-18 14:08 ` cvs-commit at gcc dot gnu.org
  8 siblings, 0 replies; 12+ messages in thread
From: pinskia at gcc dot gnu.org @ 2023-05-16 19:41 UTC (permalink / raw)
  To: gcc-bugs

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

Andrew Pinski <pinskia at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |NEW
           Assignee|bkoz at gcc dot gnu.org            |unassigned at gcc dot gnu.org

--- Comment #11 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
Unassigning since Benjamin since not been active in GCC development for over 8
years now.

^ permalink raw reply	[flat|nested] 12+ messages in thread

* [Bug libstdc++/40380] class documentation should mention include file to use
       [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
                   ` (7 preceding siblings ...)
  2023-05-16 19:41 ` pinskia at gcc dot gnu.org
@ 2024-03-18 14:08 ` cvs-commit at gcc dot gnu.org
  8 siblings, 0 replies; 12+ messages in thread
From: cvs-commit at gcc dot gnu.org @ 2024-03-18 14:08 UTC (permalink / raw)
  To: gcc-bugs

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

--- Comment #12 from GCC Commits <cvs-commit at gcc dot gnu.org> ---
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)

^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2024-03-18 14:08 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2009-06-08 21:36 [Bug libstdc++/40380] New: class documentation should mention include file to use tromey at gcc dot gnu dot org
2009-06-18  0:00 ` [Bug libstdc++/40380] " bkoz at gcc dot gnu dot org
2009-06-18  0:34 ` bkoz at gcc dot gnu dot org
     [not found] <bug-40380-4@http.gcc.gnu.org/bugzilla/>
2012-05-02 22:58 ` bkoz at gcc dot gnu.org
2021-07-01 20:11 ` redi at gcc dot gnu.org
2021-07-21 18:52 ` redi at gcc dot gnu.org
2023-04-27 10:29 ` cvs-commit at gcc dot gnu.org
2023-04-27 10:42 ` redi at gcc dot gnu.org
2023-04-27 16:00 ` redi at gcc dot gnu.org
2023-04-28 13:10 ` cvs-commit at gcc dot gnu.org
2023-05-16 19:41 ` pinskia at gcc dot gnu.org
2024-03-18 14:08 ` 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).