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

[Jonathan Wakely <jwakely@redhat.com>]

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
>