[PATCH] libstdc++: Use ///< for inline documentation

[PATCH] libstdc++: Use ///< for inline documentation

[Arsen Arsenović]

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(-)

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

Re: [PATCH] libstdc++: Use ///< for inline documentation

[Jonathan Wakely]

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
>

Re: [PATCH] libstdc++: Use ///< for inline documentation

[Arsen Arsenović]

[-- Attachment #1: Type: text/plain, Size: 856 bytes --]

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
-- 
Arsen Arsenović

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 358 bytes --]

Re: [PATCH] libstdc++: Use ///< for inline documentation

[Jonathan Wakely]

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ć