llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang-tools-extra Author: Zeyi Xu (zeyi2) <details> <summary>Changes</summary> Tracking issue: #<!-- -->201242 See the [migration guide] for more information. [migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines This is the second part of rewriting check documentations in modernize module from reST to MyST Markdown. AI Usage: This was prepared with rnk's fork of rst2myst and GPT5.6-assisted (both Codex and AmpCode) cleanup. I manually verified that the documentation renders as expected. Preview site: https://broken.life/llvm-staging/modernize-markdown-port/index.html --- Patch is 52.98 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/232214.diff 10 Files Affected: - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/pass-by-value.md (+98-103) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/raw-string-literal.md (+37-34) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/replace-auto-ptr.md (+51-54) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/replace-disallow-copy-and-assign-macro.md (+30-31) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/replace-random-shuffle.md (+29-29) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/type-traits.md (+35-37) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/use-auto.md (+154-155) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/use-constraints.md (+52-53) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/use-default-member-init.md (+63-54) - (modified) clang-tools-extra/docs/clang-tidy/checks/modernize/use-designated-initializers.md (+44-35) ``````````diff diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/pass-by-value.md b/clang-tools-extra/docs/clang-tidy/checks/modernize/pass-by-value.md index 0f5758dc097e6..d09cf81282a69 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/modernize/pass-by-value.md +++ b/clang-tools-extra/docs/clang-tidy/checks/modernize/pass-by-value.md @@ -1,7 +1,7 @@ -.. title:: clang-tidy - modernize-pass-by-value +```{title} clang-tidy - modernize-pass-by-value +``` -modernize-pass-by-value -======================= +# modernize-pass-by-value With move semantics added to the language and the standard library updated with move constructors added for many types it is now interesting to take an @@ -13,159 +13,154 @@ The transformation is usually beneficial when the calling code passes an *rvalue* and assumes the move construction is a cheap operation. This short example illustrates how the construction of the value happens: -.. code-block:: c++ +```c++ +void foo(std::string s); +std::string get_str(); - void foo(std::string s); - std::string get_str(); +void f(const std::string &str) { + foo(str); // lvalue -> copy construction + foo(get_str()); // prvalue -> move construction +} +``` - void f(const std::string &str) { - foo(str); // lvalue -> copy construction - foo(get_str()); // prvalue -> move construction - } +```{note} +Currently, only constructors are transformed to make use of pass-by-value. +Contributions that handle other situations are welcome! +``` -.. note:: - - Currently, only constructors are transformed to make use of pass-by-value. - Contributions that handle other situations are welcome! - - -Pass-by-value in constructors ------------------------------ +## Pass-by-value in constructors Replaces the uses of const-references constructor parameters that are copied into class fields. The parameter is then moved with `std::move()`. -Since ``std::move()`` is a library function declared in `<utility>` it may be +Since `std::move()` is a library function declared in `<utility>` it may be necessary to add this include. The check will add the include directive when necessary. -.. code-block:: c++ - - #include <string> +```c++ + #include <string> - class Foo { - public: - - Foo(const std::string &Copied, const std::string &ReadOnly) - - : Copied(Copied), ReadOnly(ReadOnly) - + Foo(std::string Copied, const std::string &ReadOnly) - + : Copied(std::move(Copied)), ReadOnly(ReadOnly) - {} + class Foo { + public: +- Foo(const std::string &Copied, const std::string &ReadOnly) +- : Copied(Copied), ReadOnly(ReadOnly) ++ Foo(std::string Copied, const std::string &ReadOnly) ++ : Copied(std::move(Copied)), ReadOnly(ReadOnly) + {} - private: - std::string Copied; - const std::string &ReadOnly; - }; + private: + std::string Copied; + const std::string &ReadOnly; + }; - std::string get_cwd(); - - void f(const std::string &Path) { - // The parameter corresponding to 'get_cwd()' is move-constructed. By - // using pass-by-value in the Foo constructor we managed to avoid a - // copy-construction. - Foo foo(get_cwd(), Path); - } + std::string get_cwd(); + void f(const std::string &Path) { + // The parameter corresponding to 'get_cwd()' is move-constructed. By + // using pass-by-value in the Foo constructor we managed to avoid a + // copy-construction. + Foo foo(get_cwd(), Path); + } +``` If the parameter is used more than once no transformation is performed since moved objects have an undefined state. It means the following code will be left untouched: -.. code-block:: c++ - - #include <string> +```c++ +#include <string> - void pass(const std::string &S); +void pass(const std::string &S); - struct Foo { - Foo(const std::string &S) : Str(S) { - pass(S); - } - - std::string Str; - }; +struct Foo { + Foo(const std::string &S) : Str(S) { + pass(S); + } + std::string Str; +}; +``` -Limitations ------------ +## Limitations A situation where the generated code can be wrong is when the object referenced is modified before the assignment in the init-list through a "hidden" reference. Example: -.. code-block:: c++ +```c++ + std::string s("foo"); - std::string s("foo"); - - struct Base { - Base() { - s = "bar"; - } - }; - - struct Derived : Base { - - Derived(const std::string &S) : Field(S) - + Derived(std::string S) : Field(std::move(S)) - { } + struct Base { + Base() { + s = "bar"; + } + }; - std::string Field; - }; + struct Derived : Base { +- Derived(const std::string &S) : Field(S) ++ Derived(std::string S) : Field(std::move(S)) + { } - void f() { - - Derived d(s); // d.Field holds "bar" - + Derived d(s); // d.Field holds "foo" - } + std::string Field; + }; + void f() { +- Derived d(s); // d.Field holds "bar" ++ Derived d(s); // d.Field holds "foo" + } +``` -Note about delayed template parsing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### Note about delayed template parsing When delayed template parsing is enabled, constructors part of templated contexts; templated constructors, constructors in class templates, constructors of inner classes of template classes, etc., are not transformed. Delayed template parsing is enabled by default on Windows as a Microsoft extension: -`Clang Compiler User's Manual - Microsoft extensions`_. +[Clang Compiler User's Manual - Microsoft extensions][clang compiler user's manual - microsoft extensions]. Delayed template parsing can be enabled using the `-fdelayed-template-parsing` flag and disabled using `-fno-delayed-template-parsing`. Example: -.. code-block:: c++ +```c++ + template <typename T> class C { + std::string S; - template <typename T> class C { - std::string S; + public: += // using -fdelayed-template-parsing (default on Windows) += C(const std::string &S) : S(S) {} - public: - = // using -fdelayed-template-parsing (default on Windows) - = C(const std::string &S) : S(S) {} - - + // using -fno-delayed-template-parsing (default on non-Windows systems) - + C(std::string S) : S(std::move(S)) {} - }; - -.. _Clang Compiler User's Manual - Microsoft extensions: https://clang.llvm.org/docs/UsersManual.html#microsoft-extensions - -.. seealso:: ++ // using -fno-delayed-template-parsing (default on non-Windows systems) ++ C(std::string S) : S(std::move(S)) {} + }; +``` - For more information about the pass-by-value idiom, read: `Want Speed? Pass by Value`_. +```{seealso} +For more information about the pass-by-value idiom, read: [Want Speed? Pass by Value](https://web.archive.org/web/20140205194657/http://cpp-next.com/archive/2009/08/want-speed-pass-by-value/). +``` - .. _Want Speed? Pass by Value: https://web.archive.org/web/20140205194657/http://cpp-next.com/archive/2009/08/want-speed-pass-by-value/ +## Options -Options -------- +(modernize-pass-by-value-include-style)= -.. option:: IncludeStyle +```{option} IncludeStyle +A string specifying which include-style is used, `llvm` or `google`. Default is `llvm`. +``` - A string specifying which include-style is used, `llvm` or `google`. Default - is `llvm`. +(modernize-pass-by-value-values-only)= -.. option:: ValuesOnly +```{option} ValuesOnly +When `true`, the check only warns about copied parameters that are already +passed by value. Default is `false`. +``` - When `true`, the check only warns about copied parameters that are already - passed by value. Default is `false`. +(modernize-pass-by-value-ignore-macros)= -.. option:: IgnoreMacros +```{option} IgnoreMacros +When `true`, the check will not give warnings inside macros. Default is +`false`. +``` - When `true`, the check will not give warnings inside macros. Default is - `false`. +[clang compiler user's manual - microsoft extensions]: https://clang.llvm.org/docs/UsersManual.html#microsoft-extensions diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/raw-string-literal.md b/clang-tools-extra/docs/clang-tidy/checks/modernize/raw-string-literal.md index 66e50e80fa70b..23174a7a2e9f4 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/modernize/raw-string-literal.md +++ b/clang-tools-extra/docs/clang-tidy/checks/modernize/raw-string-literal.md @@ -1,39 +1,39 @@ -.. title:: clang-tidy - modernize-raw-string-literal +```{title} clang-tidy - modernize-raw-string-literal +``` -modernize-raw-string-literal -============================ +# modernize-raw-string-literal This check selectively replaces string literals containing escaped characters with raw string literals. Example: -.. code-block:: c++ - - const char *const Quotes{"embedded \"quotes\""}; - const char *const Paragraph{"Line one.\nLine two.\nLine three.\n"}; - const char *const SingleLine{"Single line.\n"}; - const char *const TrailingSpace{"Look here -> \n"}; - const char *const Tab{"One\tTwo\n"}; - const char *const Bell{"Hello!\a And welcome!"}; - const char *const Path{"C:\\Program Files\\Vendor\\Application.exe"}; - const char *const RegEx{"\\w\\([a-z]\\)"}; +```c++ +const char *const Quotes{"embedded \"quotes\""}; +const char *const Paragraph{"Line one.\nLine two.\nLine three.\n"}; +const char *const SingleLine{"Single line.\n"}; +const char *const TrailingSpace{"Look here -> \n"}; +const char *const Tab{"One\tTwo\n"}; +const char *const Bell{"Hello!\a And welcome!"}; +const char *const Path{"C:\\Program Files\\Vendor\\Application.exe"}; +const char *const RegEx{"\\w\\([a-z]\\)"}; +``` becomes -.. code-block:: c++ - - const char *const Quotes{R"(embedded "quotes")"}; - const char *const Paragraph{"Line one.\nLine two.\nLine three.\n"}; - const char *const SingleLine{"Single line.\n"}; - const char *const TrailingSpace{"Look here -> \n"}; - const char *const Tab{"One\tTwo\n"}; - const char *const Bell{"Hello!\a And welcome!"}; - const char *const Path{R"(C:\Program Files\Vendor\Application.exe)"}; - const char *const RegEx{R"(\w\([a-z]\))"}; +```c++ +const char *const Quotes{R"(embedded "quotes")"}; +const char *const Paragraph{"Line one.\nLine two.\nLine three.\n"}; +const char *const SingleLine{"Single line.\n"}; +const char *const TrailingSpace{"Look here -> \n"}; +const char *const Tab{"One\tTwo\n"}; +const char *const Bell{"Hello!\a And welcome!"}; +const char *const Path{R"(C:\Program Files\Vendor\Application.exe)"}; +const char *const RegEx{R"(\w\([a-z]\))"}; +``` The presence of any of the following escapes can cause the string to be -converted to a raw string literal: ``\\``, ``\'``, ``\"``, ``\?``, +converted to a raw string literal: `\\`, `\'`, `\"`, `\?`, and octal or hexadecimal escapes for printable ASCII characters. A string literal containing only escaped newlines is a common way of @@ -45,17 +45,20 @@ An escaped horizontal tab, form feed, or vertical tab prevents the string literal from being converted. The presence of a horizontal tab, form feed or vertical tab in source code is not visually obvious. -Options -------- +## Options -.. option:: DelimiterStem +(modernize-raw-string-literal-delimiter-stem)= - Custom delimiter to escape characters in raw string literals. It is used in - the following construction: ``R"stem_delimiter(contents)stem_delimiter"``. - The default value is `lit`. +```{option} DelimiterStem +Custom delimiter to escape characters in raw string literals. It is used in +the following construction: `R"stem_delimiter(contents)stem_delimiter"`. +Default is `lit`. +``` -.. option:: ReplaceShorterLiterals +(modernize-raw-string-literal-replace-shorter-literals)= - Controls replacing shorter non-raw string literals with longer raw string - literals. Setting this option to `true` enables the replacement. - The default value is `false` (shorter literals are not replaced). +```{option} ReplaceShorterLiterals +Controls replacing shorter non-raw string literals with longer raw string +literals. Setting this option to `true` enables the replacement. +When `false`, shorter literals are not replaced. Default is `false`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-auto-ptr.md b/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-auto-ptr.md index 8a8c30e6c15a3..27e4e68b1d681 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-auto-ptr.md +++ b/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-auto-ptr.md @@ -1,81 +1,78 @@ -.. title:: clang-tidy - modernize-replace-auto-ptr +```{title} clang-tidy - modernize-replace-auto-ptr +``` -modernize-replace-auto-ptr -========================== +# modernize-replace-auto-ptr -This check replaces the uses of the deprecated class ``std::auto_ptr`` by -``std::unique_ptr`` (introduced in C++11). The transfer of ownership, done +This check replaces the uses of the deprecated class `std::auto_ptr` by +`std::unique_ptr` (introduced in C++11). The transfer of ownership, done by the copy-constructor and the assignment operator, is changed to match -``std::unique_ptr`` usage by using explicit calls to ``std::move()``. +`std::unique_ptr` usage by using explicit calls to `std::move()`. Migration example: -.. code-block:: c++ +```c++ +-void take_ownership_fn(std::auto_ptr<int> int_ptr); ++void take_ownership_fn(std::unique_ptr<int> int_ptr); - -void take_ownership_fn(std::auto_ptr<int> int_ptr); - +void take_ownership_fn(std::unique_ptr<int> int_ptr); + void f(int x) { +- std::auto_ptr<int> a(new int(x)); +- std::auto_ptr<int> b; ++ std::unique_ptr<int> a(new int(x)); ++ std::unique_ptr<int> b; - void f(int x) { - - std::auto_ptr<int> a(new int(x)); - - std::auto_ptr<int> b; - + std::unique_ptr<int> a(new int(x)); - + std::unique_ptr<int> b; +- b = a; +- take_ownership_fn(b); ++ b = std::move(a); ++ take_ownership_fn(std::move(b)); + } +``` - - b = a; - - take_ownership_fn(b); - + b = std::move(a); - + take_ownership_fn(std::move(b)); - } - -Since ``std::move()`` is a library function declared in ``<utility>`` it may be +Since `std::move()` is a library function declared in `<utility>` it may be necessary to add this include. The check will add the include directive when necessary. +## Limitations -Limitations ------------ - -* If headers modification is not activated or if a header is not allowed to be +- If headers modification is not activated or if a header is not allowed to be changed this check will produce broken code (compilation error), where the headers' code will stay unchanged while the code using them will be changed. - -* Client code that declares a reference to an ``std::auto_ptr`` coming from - code that can't be migrated (such as a header coming from a 3\ :sup:`rd` +- Client code that declares a reference to an `std::auto_ptr` coming from + code that can't be migrated (such as a header coming from a 3{sup}`rd` party library) will produce a compilation error after migration. This is - because the type of the reference will be changed to ``std::unique_ptr`` but + because the type of the reference will be changed to `std::unique_ptr` but the type returned by the library won't change, binding a reference to - ``std::unique_ptr`` from an ``std::auto_ptr``. This pattern doesn't make much - sense and usually ``std::auto_ptr`` are stored by value (otherwise what is + `std::unique_ptr` from an `std::auto_ptr`. This pattern doesn't make much + sense and usually `std::auto_ptr` are stored by value (otherwise what is the point in using them instead of a reference or a pointer?). -.. code-block:: c++ - - // <3rd-party header...> - std::auto_ptr<int> get_value(); - const std::auto_ptr<int> & get_ref(); - - // <calling code (with migration)...> - -std::auto_ptr<int> a(get_value()); - +std::unique_ptr<int> a(get_value()); // ok, unique_ptr constructed from auto_ptr +```c++ + // <3rd-party header...> + std::auto_ptr<int> get_value(); + const std::auto_ptr<int> & get_ref(); - -const std::auto_ptr<int> & p = get_ptr(); - +const std::unique_ptr<int> & p = get_ptr(); // won't compile + // <calling code (with migration)...> +-std::auto_ptr<int> a(get_value()); ++std::unique_ptr<int> a(get_value()); // ok, unique_ptr constructed from auto_ptr -* Non-instantiated templates aren't modified. +-const std::auto_ptr<int> & p = get_ptr(); ++const std::unique_ptr<int> & p = get_ptr(); // won't compile +``` -.. code-block:: c++ +- Non-instantiated templates aren't modified. - template <typename X> - void f() { - std::auto_ptr<X> p; - } +```c++ +template <typename X> +void f() { + std::auto_ptr<X> p; +} - // only 'f<int>()' (or similar) will trigger the replacement. +// only 'f<int>()' (or similar) will trigger the replacement. +``` -Options -------- +## Options -.. option:: IncludeStyle +(modernize-replace-auto-ptr-include-style)= - A string specifying which include-style is used, `llvm` or `google`. Default - is `llvm`. +```{option} IncludeStyle +A string specifying which include-style is used, `llvm` or `google`. Default is `llvm`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-disallow-copy-and-assign-macro.md b/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-disallow-copy-and-assign-macro.md index 485abca339050..ec0b17778ad48 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-disallow-copy-and-assign-macro.md +++ b/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-disallow-copy-and-assign-macro.md @@ -1,53 +1,52 @@ -.. title:: clang-tidy - modernize-replace-disallow-copy-and-assign-macro +```{title} clang-tidy - modernize-replace-disallow-copy-and-assign-macro +``` -modernize-replace-disallow-copy-and-assign-macro -================================================ +# modernize-replace-disallow-copy-and-assign-macro -Finds macro expansions of ``DISALLOW_COPY_AND_ASSIGN(Type)`` and replaces them +Finds macro expansions of `DISALLOW_COPY_AND_ASSIGN(Type)` and replaces them with a deleted copy constructor and a deleted assignment operator. -Before the ``delete`` keyword was introduced in C++11 it was common practice to +Before the `delete` keyword was introduced in C++11 it was common practice to declare a copy constructor and an assignment operator as private members. This effectively makes them unusable to the public API of a class. -With the advent of the ``delete`` keyword in C++11 we can abandon the -``private`` access of the copy constructor and the assignment operator and +With the advent of the `delete` keyword in C++11 we can abandon the +`private` access of the copy constructor and the assignment operator and delete the methods entirely. When running this check on a code like this: -.. code-block:: c++ - - class Foo { - private: - DISALLOW_COPY_AND_ASSIGN(Foo); - }; +```c++ +class Foo { +private: + DISALLOW_COPY_AND_ASSIGN(Foo); +}; +``` It will be transformed to this: -.. code-block:: c++ - - class Foo { - private: - Foo(const Foo &) = delete; - const Foo &operator=(const Foo &) = delete; - }; - +```c++ +class Foo { +private: + Foo(const Foo &) = delete; + const Foo &operator=(const Foo &) = delete; +}; +``` -Limitations ------------ +## Limitations -* Notice that the migration example above leaves the ``private`` access +- Notice that the migration example above leaves the `private` access specification untouched. You might want to run the check - :doc:`modernize-use-equals-delete <../modernize/use-equals-delete>` + {doc}`modernize-use-equals-delete <../modernize/use-equals-delete>` to get warnings for deleted functions in private sections. -Options -------- +## Options -.. option:: MacroName +(modernize-replace-disallow-copy-and-assign-macro-macro-name)= - A string specifying the macro name whose expansion will be replaced. - Default is `DISALLOW_COPY_AND_ASSIGN`. +```{option} MacroName +A string specifying the macro name whose expansion will be replaced. +Default is `DISALLOW_COPY_AND_ASSIGN`. +``` -See: https://en.cppreference.com/w/cpp/language/function#Deleted_functions +See: <https://en.cppreference.com/w/cpp/language/function#Deleted_functions> diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize/replace-random-shuffle.md b/clang-tools-extra/docs/clang-tidy/checks/mo... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/232214 _______________________________________________ llvm-branch-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-branch-commits
