libstdc++: Use ///< for inline documentation
Checks
Commit Message
I accidentally that some variables were misdocumented when using
trailing comment for documentation. I ran a search with a relatively
simple regex[1] to look for any ///s following some code that did not
have a <, and came up with these instances only.
[1]: \s*([^ ]+\s*)+///[^<].*$
libstdc++-v3/ChangeLog:
* include/std/iostream: Use ///< for inline documentation.
* include/std/limits: Likewise.
* include/experimental/internet: Likewise.
Signed-off-by: Arsen Arsenović <arsen@aarsen.me>
---
Hey,
I just got reminded that I found some trivial documentation errors a few months
ago, and forgot to do anything about them after bringing them up on IRC. This
patch should fix that.
Thanks,
libstdc++-v3/include/experimental/internet | 2 +-
libstdc++-v3/include/std/iostream | 16 ++++++++--------
libstdc++-v3/include/std/limits | 10 +++++-----
3 files changed, 14 insertions(+), 14 deletions(-)
Comments
On Sat, 1 Oct 2022 at 19:43, Arsen Arsenović via Libstdc++
<libstdc++@gcc.gnu.org> wrote:
>
> I accidentally that some variables were misdocumented when using
> trailing comment for documentation. I ran a search with a relatively
> simple regex[1] to look for any ///s following some code that did not
> have a <, and came up with these instances only.
>
> [1]: \s*([^ ]+\s*)+///[^<].*$
>
> libstdc++-v3/ChangeLog:
> * include/std/iostream: Use ///< for inline documentation.
> * include/std/limits: Likewise.
> * include/experimental/internet: Likewise.
>
> Signed-off-by: Arsen Arsenović <arsen@aarsen.me>
> ---
> Hey,
>
> I just got reminded that I found some trivial documentation errors a few months
> ago, and forgot to do anything about them after bringing them up on IRC. This
> patch should fix that.
I did look into this after you pointed it out on IRC. Unless I fumbled
my doxygen roll, the results are the same for /// and ///< so maybe at
some point Doxygen started to DTRT even without the < character.
>
> Thanks,
>
> libstdc++-v3/include/experimental/internet | 2 +-
> libstdc++-v3/include/std/iostream | 16 ++++++++--------
> libstdc++-v3/include/std/limits | 10 +++++-----
> 3 files changed, 14 insertions(+), 14 deletions(-)
>
> diff --git a/libstdc++-v3/include/experimental/internet b/libstdc++-v3/include/experimental/internet
> index 4be4bfb731e..a6b7b235087 100644
> --- a/libstdc++-v3/include/experimental/internet
> +++ b/libstdc++-v3/include/experimental/internet
> @@ -2137,7 +2137,7 @@ namespace ip
> using resolver = basic_resolver<tcp>; ///< A TCP resolver.
> using socket = basic_stream_socket<tcp>; ///< A TCP socket.
> using acceptor = basic_socket_acceptor<tcp>; ///< A TCP acceptor.
> - using iostream = basic_socket_iostream<tcp>; /// A TCP iostream.
> + using iostream = basic_socket_iostream<tcp>; ///< A TCP iostream.
>
> #ifdef TCP_NODELAY
> /// Disable coalescing of small segments (i.e. the Nagle algorithm).
> diff --git a/libstdc++-v3/include/std/iostream b/libstdc++-v3/include/std/iostream
> index d705913f53c..83a238193ce 100644
> --- a/libstdc++-v3/include/std/iostream
> +++ b/libstdc++-v3/include/std/iostream
> @@ -57,16 +57,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> * manual linked to above.
> */
> ///@{
> - extern istream cin; /// Linked to standard input
> - extern ostream cout; /// Linked to standard output
> - extern ostream cerr; /// Linked to standard error (unbuffered)
> - extern ostream clog; /// Linked to standard error (buffered)
> + extern istream cin; ///< Linked to standard input
> + extern ostream cout; ///< Linked to standard output
> + extern ostream cerr; ///< Linked to standard error (unbuffered)
> + extern ostream clog; ///< Linked to standard error (buffered)
>
> #ifdef _GLIBCXX_USE_WCHAR_T
> - extern wistream wcin; /// Linked to standard input
> - extern wostream wcout; /// Linked to standard output
> - extern wostream wcerr; /// Linked to standard error (unbuffered)
> - extern wostream wclog; /// Linked to standard error (buffered)
> + extern wistream wcin; ///< Linked to standard input
> + extern wostream wcout; ///< Linked to standard output
> + extern wostream wcerr; ///< Linked to standard error (unbuffered)
> + extern wostream wclog; ///< Linked to standard error (buffered)
> #endif
> ///@}
>
> diff --git a/libstdc++-v3/include/std/limits b/libstdc++-v3/include/std/limits
> index 66201fa6215..a60611b1b11 100644
> --- a/libstdc++-v3/include/std/limits
> +++ b/libstdc++-v3/include/std/limits
> @@ -166,11 +166,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
> */
> enum float_round_style
> {
> - round_indeterminate = -1, /// Intermediate.
> - round_toward_zero = 0, /// To zero.
> - round_to_nearest = 1, /// To the nearest representable value.
> - round_toward_infinity = 2, /// To infinity.
> - round_toward_neg_infinity = 3 /// To negative infinity.
> + round_indeterminate = -1, ///< Intermediate.
> + round_toward_zero = 0, ///< To zero.
> + round_to_nearest = 1, ///< To the nearest representable value.
> + round_toward_infinity = 2, ///< To infinity.
> + round_toward_neg_infinity = 3 ///< To negative infinity.
> };
>
> /**
> --
> 2.37.3
>
On Monday, 3 October 2022 10:37:00 CEST Jonathan Wakely wrote:
> I did look into this after you pointed it out on IRC. Unless I fumbled
> my doxygen roll, the results are the same for /// and ///< so maybe
> at some point Doxygen started to DTRT even without the < character.
It is actually unchanged for the standard IO objects, for some reason.
The rounding style enum produced different results after this change
(for convenience, link below; intermediate is missing, towards_zero is
misdocumented).
Unsure what the exact rule is, but, AFAICT, ///< is not worse, and on
top of that, clangd interprets it properly (it's how I stumbled upon
this, cout was "Linked to standard output" in its LSP hover response).
https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01635.html#a53dbc8572a84ca50272f9e55a1e23e18
On Mon, 3 Oct 2022 at 10:29, Arsen Arsenović wrote:
>
> On Monday, 3 October 2022 10:37:00 CEST Jonathan Wakely wrote:
> > I did look into this after you pointed it out on IRC. Unless I fumbled
> > my doxygen roll, the results are the same for /// and ///< so maybe
> > at some point Doxygen started to DTRT even without the < character.
>
> It is actually unchanged for the standard IO objects, for some reason.
Yes, those are the ones I checked.
> The rounding style enum produced different results after this change
Ah OK, thanks. I'll apply the patch then.
> (for convenience, link below; intermediate is missing, towards_zero is
> misdocumented).
>
> Unsure what the exact rule is, but, AFAICT, ///< is not worse, and on
> top of that, clangd interprets it properly (it's how I stumbled upon
> this, cout was "Linked to standard output" in its LSP hover response).
>
> https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01635.html#a53dbc8572a84ca50272f9e55a1e23e18
> --
> Arsen Arsenović
@@ -2137,7 +2137,7 @@ namespace ip
using resolver = basic_resolver<tcp>; ///< A TCP resolver.
using socket = basic_stream_socket<tcp>; ///< A TCP socket.
using acceptor = basic_socket_acceptor<tcp>; ///< A TCP acceptor.
- using iostream = basic_socket_iostream<tcp>; /// A TCP iostream.
+ using iostream = basic_socket_iostream<tcp>; ///< A TCP iostream.
#ifdef TCP_NODELAY
/// Disable coalescing of small segments (i.e. the Nagle algorithm).
@@ -57,16 +57,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* manual linked to above.
*/
///@{
- extern istream cin; /// Linked to standard input
- extern ostream cout; /// Linked to standard output
- extern ostream cerr; /// Linked to standard error (unbuffered)
- extern ostream clog; /// Linked to standard error (buffered)
+ extern istream cin; ///< Linked to standard input
+ extern ostream cout; ///< Linked to standard output
+ extern ostream cerr; ///< Linked to standard error (unbuffered)
+ extern ostream clog; ///< Linked to standard error (buffered)
#ifdef _GLIBCXX_USE_WCHAR_T
- extern wistream wcin; /// Linked to standard input
- extern wostream wcout; /// Linked to standard output
- extern wostream wcerr; /// Linked to standard error (unbuffered)
- extern wostream wclog; /// Linked to standard error (buffered)
+ extern wistream wcin; ///< Linked to standard input
+ extern wostream wcout; ///< Linked to standard output
+ extern wostream wcerr; ///< Linked to standard error (unbuffered)
+ extern wostream wclog; ///< Linked to standard error (buffered)
#endif
///@}
@@ -166,11 +166,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
*/
enum float_round_style
{
- round_indeterminate = -1, /// Intermediate.
- round_toward_zero = 0, /// To zero.
- round_to_nearest = 1, /// To the nearest representable value.
- round_toward_infinity = 2, /// To infinity.
- round_toward_neg_infinity = 3 /// To negative infinity.
+ round_indeterminate = -1, ///< Intermediate.
+ round_toward_zero = 0, ///< To zero.
+ round_to_nearest = 1, ///< To the nearest representable value.
+ round_toward_infinity = 2, ///< To infinity.
+ round_toward_neg_infinity = 3 ///< To negative infinity.
};
/**