From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id 3A19D3857006 for ; Thu, 27 Apr 2023 10:31:40 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 3A19D3857006 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682591499; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=UMle4Snjb3sxIMimFkNBrrTNt9kU7bFU0Rv2H3OaGII=; b=TctPoCEIip3Hi5D5+I5WBul8sodxjctMeUP+noALvAoIm+JL4Y3z4NWKc/0FWjwdiEst5y aUtIk4jTk8bfZhxYTb8kDceeo4afbmjxHaIs4EzK8QdiAYw8y9jD/k5YfAEU8QIRYwhlhU iGEDUdGMont0mQg/yiwnFFSRw3bfYrk= Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-528-R7fTDs5hNL-Ldbfsi3ncnA-1; Thu, 27 Apr 2023 06:31:38 -0400 X-MC-Unique: R7fTDs5hNL-Ldbfsi3ncnA-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5AD103815EEE; Thu, 27 Apr 2023 10:31:38 +0000 (UTC) Received: from localhost (unknown [10.42.28.201]) by smtp.corp.redhat.com (Postfix) with ESMTP id E090E40C6EC4; Thu, 27 Apr 2023 10:31:37 +0000 (UTC) From: Jonathan Wakely To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed] libstdc++: Add @headerfile and @since to doxygen comments [PR40380] Date: Thu, 27 Apr 2023 11:31:36 +0100 Message-Id: <20230427103136.1725804-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.2 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-12.2 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_NONE,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: Tested powerpc64le-linux. Docs tested on Fedora 37 with Doxygen 1.9.7 from current git master. Pushed to trunk. I'll probably backport this too. -- >8 -- 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. --- libstdc++-v3/include/bits/basic_string.h | 2 ++ libstdc++-v3/include/bits/cow_string.h | 2 ++ libstdc++-v3/include/bits/forward_list.h | 2 ++ libstdc++-v3/include/bits/fs_dir.h | 35 +++++++++++++++++++++-- libstdc++-v3/include/bits/fs_path.h | 18 +++++++++++- libstdc++-v3/include/bits/quoted_string.h | 12 +++++--- libstdc++-v3/include/bits/stl_bvector.h | 2 ++ libstdc++-v3/include/bits/stl_map.h | 2 ++ libstdc++-v3/include/bits/stl_multimap.h | 2 ++ libstdc++-v3/include/bits/stl_multiset.h | 3 +- libstdc++-v3/include/bits/stl_set.h | 2 ++ libstdc++-v3/include/bits/stl_vector.h | 2 ++ libstdc++-v3/include/bits/unordered_map.h | 4 +++ libstdc++-v3/include/bits/unordered_set.h | 4 +++ libstdc++-v3/include/std/filesystem | 2 ++ libstdc++-v3/include/std/iomanip | 1 + 16 files changed, 87 insertions(+), 8 deletions(-) diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h index 5d040e2897d..8247ee6bdc6 100644 --- a/libstdc++-v3/include/bits/basic_string.h +++ b/libstdc++-v3/include/bits/basic_string.h @@ -69,6 +69,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * * @ingroup strings * @ingroup sequences + * @headerfile string + * @since C++98 * * @tparam _CharT Type of character * @tparam _Traits Traits for character type, defaults to diff --git a/libstdc++-v3/include/bits/cow_string.h b/libstdc++-v3/include/bits/cow_string.h index b6024365d4f..e5f094fd13e 100644 --- a/libstdc++-v3/include/bits/cow_string.h +++ b/libstdc++-v3/include/bits/cow_string.h @@ -54,6 +54,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * * @ingroup strings * @ingroup sequences + * @headerfile string + * @since C++98 * * @tparam _CharT Type of character * @tparam _Traits Traits for character type, defaults to diff --git a/libstdc++-v3/include/bits/forward_list.h b/libstdc++-v3/include/bits/forward_list.h index e1e68bd7e04..72b1ef46d14 100644 --- a/libstdc++-v3/include/bits/forward_list.h +++ b/libstdc++-v3/include/bits/forward_list.h @@ -406,6 +406,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * and fixed time insertion/deletion at any point in the sequence. * * @ingroup sequences + * @headerfile forward_list + * @since C++11 * * @tparam _Tp Type of element. * @tparam _Alloc Allocator type, defaults to allocator<_Tp>. diff --git a/libstdc++-v3/include/bits/fs_dir.h b/libstdc++-v3/include/bits/fs_dir.h index b4adf49e94a..9dd0f896e46 100644 --- a/libstdc++-v3/include/bits/fs_dir.h +++ b/libstdc++-v3/include/bits/fs_dir.h @@ -52,6 +52,10 @@ namespace filesystem */ /// Information about a file's type and permissions. + /** + * @headerfile filesystem + * @since C++17 + */ class file_status { public: @@ -94,6 +98,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 class recursive_directory_iterator; /// The value type used by directory iterators + /** + * @headerfile filesystem + * @since C++17 + */ class directory_entry { public: @@ -354,7 +362,13 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 file_type _M_type = file_type::none; }; + /// @cond undocumented + /// Proxy returned by post-increment on directory iterators. + /** + * @headerfile filesystem + * @since C++17 + */ struct __directory_iterator_proxy { const directory_entry& operator*() const& noexcept { return _M_entry; } @@ -370,8 +384,13 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 directory_entry _M_entry; }; + /// @endcond /// Iterator type for traversing the entries in a single directory. + /** + * @headerfile filesystem + * @since C++17 + */ class directory_iterator { public: @@ -451,7 +470,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 std::__shared_ptr<_Dir> _M_dir; }; - /// @relates std::filesystem::directory_iterator @{ + /** @relates std::filesystem::directory_iterator + * @headerfile filesystem + * @since C++17 + * @{ + */ /** @brief Enable range-based `for` using directory_iterator. * @@ -468,6 +491,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /// @} /// Iterator type for recursively traversing a directory hierarchy. + /** + * @headerfile filesystem + * @since C++17 + */ class recursive_directory_iterator { public: @@ -566,7 +593,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 filesystem::remove_all(const path&); }; - /// @relates std::filesystem::recursive_directory_iterator @{ + /** @relates std::filesystem::directory_iterator + * @headerfile filesystem + * @since C++17 + * @{ + */ /** @brief Enable range-based `for` using recursive_directory_iterator. * diff --git a/libstdc++-v3/include/bits/fs_path.h b/libstdc++-v3/include/bits/fs_path.h index 0d7bb10c1a0..853c55f0100 100644 --- a/libstdc++-v3/include/bits/fs_path.h +++ b/libstdc++-v3/include/bits/fs_path.h @@ -285,7 +285,11 @@ namespace __detail /// @{ /// A filesystem path - /// @ingroup filesystem + /** + * @ingroup filesystem + * @headerfile filesystem + * @since C++17 + */ class path { public: @@ -736,6 +740,10 @@ namespace __detail /// @} /// Exception type thrown by the Filesystem library + /** + * @headerfile filesystem + * @since C++17 + */ class filesystem_error : public std::system_error { public: @@ -798,6 +806,8 @@ namespace __detail /** Create a path from a UTF-8-encoded sequence of char * * @relates std::filesystem::path + * @headerfile filesystem + * @since C++17 */ template, @@ -822,6 +832,8 @@ namespace __detail /** Create a path from a UTF-8-encoded sequence of char * * @relates std::filesystem::path + * @headerfile filesystem + * @since C++17 */ template, @@ -923,6 +935,10 @@ namespace __detail /// @endcond /// An iterator for the components of a path + /** + * @headerfile filesystem + * @since C++17 + */ class path::iterator { public: diff --git a/libstdc++-v3/include/bits/quoted_string.h b/libstdc++-v3/include/bits/quoted_string.h index 0644b077d71..ae961a9f254 100644 --- a/libstdc++-v3/include/bits/quoted_string.h +++ b/libstdc++-v3/include/bits/quoted_string.h @@ -85,14 +85,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Inserter for quoted strings. * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 2344 quoted()'s interaction with padding is unclear + * @headerfile iomanip */ template std::basic_ostream<_CharT, _Traits>& operator<<(std::basic_ostream<_CharT, _Traits>& __os, const _Quoted_string& __str) { + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 2344 quoted()'s interaction with padding is unclear std::basic_ostringstream<_CharT, _Traits> __ostr; __ostr << __str._M_delim; for (const _CharT* __c = __str._M_string; *__c; ++__c) @@ -109,14 +110,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Inserter for quoted strings. * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 2344 quoted()'s interaction with padding is unclear + * @headerfile iomanip */ template std::basic_ostream<_CharT, _Traits>& operator<<(std::basic_ostream<_CharT, _Traits>& __os, const _Quoted_string<_String, _CharT>& __str) { + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 2344 quoted()'s interaction with padding is unclear std::basic_ostringstream<_CharT, _Traits> __ostr; __ostr << __str._M_delim; for (auto __c : __str._M_string) @@ -133,6 +135,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Extractor for delimited strings. * The left and right delimiters can be different. + * + * @headerfile iomanip */ template std::basic_istream<_CharT, _Traits>& diff --git a/libstdc++-v3/include/bits/stl_bvector.h b/libstdc++-v3/include/bits/stl_bvector.h index d4d4bfca588..ad462c5933c 100644 --- a/libstdc++-v3/include/bits/stl_bvector.h +++ b/libstdc++-v3/include/bits/stl_bvector.h @@ -684,6 +684,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * access to individual elements in any order. * * @ingroup sequences + * @headerfile vector + * @since C++98 * * @tparam _Alloc Allocator type. * diff --git a/libstdc++-v3/include/bits/stl_map.h b/libstdc++-v3/include/bits/stl_map.h index e1ce90ea5a4..059916d0a7f 100644 --- a/libstdc++-v3/include/bits/stl_map.h +++ b/libstdc++-v3/include/bits/stl_map.h @@ -76,6 +76,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * retrieved based on a key, in logarithmic time. * * @ingroup associative_containers + * @headerfile map + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. diff --git a/libstdc++-v3/include/bits/stl_multimap.h b/libstdc++-v3/include/bits/stl_multimap.h index 6b11d4b3eaf..2efd53d4680 100644 --- a/libstdc++-v3/include/bits/stl_multimap.h +++ b/libstdc++-v3/include/bits/stl_multimap.h @@ -74,6 +74,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * retrieved based on a key, in logarithmic time. * * @ingroup associative_containers + * @headerfile map + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. diff --git a/libstdc++-v3/include/bits/stl_multiset.h b/libstdc++-v3/include/bits/stl_multiset.h index 8f70f89f7b1..a3998775d94 100644 --- a/libstdc++-v3/include/bits/stl_multiset.h +++ b/libstdc++-v3/include/bits/stl_multiset.h @@ -74,7 +74,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * in logarithmic time. * * @ingroup associative_containers - * + * @headerfile set + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Compare Comparison function object type, defaults to less<_Key>. diff --git a/libstdc++-v3/include/bits/stl_set.h b/libstdc++-v3/include/bits/stl_set.h index 9ce05e0da6e..ddaf7fec738 100644 --- a/libstdc++-v3/include/bits/stl_set.h +++ b/libstdc++-v3/include/bits/stl_set.h @@ -74,6 +74,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * retrieved in logarithmic time. * * @ingroup associative_containers + * @headerfile set + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Compare Comparison function object type, defaults to less<_Key>. diff --git a/libstdc++-v3/include/bits/stl_vector.h b/libstdc++-v3/include/bits/stl_vector.h index 86ff83d1373..acb29396d26 100644 --- a/libstdc++-v3/include/bits/stl_vector.h +++ b/libstdc++-v3/include/bits/stl_vector.h @@ -403,6 +403,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * individual elements in any order. * * @ingroup sequences + * @headerfile vector + * @since C++98 * * @tparam _Tp Type of element. * @tparam _Alloc Allocator type, defaults to allocator<_Tp>. diff --git a/libstdc++-v3/include/bits/unordered_map.h b/libstdc++-v3/include/bits/unordered_map.h index f11ccdac07a..2f63bc5f1fa 100644 --- a/libstdc++-v3/include/bits/unordered_map.h +++ b/libstdc++-v3/include/bits/unordered_map.h @@ -83,6 +83,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * with the keys. * * @ingroup unordered_associative_containers + * @headerfile unordered_map + * @since C++11 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. @@ -1226,6 +1228,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * values of another type with the keys. * * @ingroup unordered_associative_containers + * @headerfile unordered_map + * @since C++11 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. diff --git a/libstdc++-v3/include/bits/unordered_set.h b/libstdc++-v3/include/bits/unordered_set.h index 68fcfd2ec66..f3b0c078baa 100644 --- a/libstdc++-v3/include/bits/unordered_set.h +++ b/libstdc++-v3/include/bits/unordered_set.h @@ -80,6 +80,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * the elements themselves. * * @ingroup unordered_associative_containers + * @headerfile unordered_set + * @since C++11 * * @tparam _Value Type of key objects. * @tparam _Hash Hashing function object type, defaults to hash<_Value>. @@ -948,6 +950,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * elements' keys are the elements themselves. * * @ingroup unordered_associative_containers + * @headerfile unordered_set + * @since C++11 * * @tparam _Value Type of key objects. * @tparam _Hash Hashing function object type, defaults to hash<_Value>. diff --git a/libstdc++-v3/include/std/filesystem b/libstdc++-v3/include/std/filesystem index eff2b934f56..d46e842826d 100644 --- a/libstdc++-v3/include/std/filesystem +++ b/libstdc++-v3/include/std/filesystem @@ -41,6 +41,8 @@ * * Utilities for performing operations on file systems and their components, * such as paths, regular files, and directories. + * + * @since C++17 */ #include diff --git a/libstdc++-v3/include/std/iomanip b/libstdc++-v3/include/std/iomanip index a536665566b..5c0fb09a60e 100644 --- a/libstdc++-v3/include/std/iomanip +++ b/libstdc++-v3/include/std/iomanip @@ -457,6 +457,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @param __string String to quote. * @param __delim Character to quote string with. * @param __escape Escape character to escape itself or quote character. + * @since C++14 */ template inline auto -- 2.40.0