[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite modernize check docs to Markdown [2/4] (PR #232214)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Oct 15 00:56:13 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang-tidy
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
More information about the llvm-branch-commits
mailing list