[llvm-branch-commits] [clang-tools-extra] [clang-tidy][docs] Rewrite remaining abseil check docs to Markdown (PR #212004)
via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sat Jul 25 02:17:51 PDT 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang-tidy
Author: Zeyi Xu (zeyi2)
<details>
<summary>Changes</summary>
This commit rewrites the reST documentation to Markdown.
Tracking issue: #<!-- -->201242
See the [migration guide] for more information.
[migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
AI Usage: This was prepared with rst2myst and GPT5.6-assisted cleanup, I manually verified that all the documentations render the same as before.
Preview site for reviewing: https://broken.life/llvm-staging/abseil-markdown-port/
---
Patch is 49.79 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/212004.diff
12 Files Affected:
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/duration-comparison.md (+20-20)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/duration-conversion-cast.md (+17-18)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/duration-division.md (+24-25)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/duration-factory-scale.md (+21-21)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/duration-subtraction.md (+21-22)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/duration-unnecessary-conversion.md (+35-35)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/faster-strsplit-delimiter.md (+23-23)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/string-find-startswith.md (+32-32)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/string-find-str-contains.md (+34-33)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/time-subtraction.md (+22-22)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/unchecked-statusor-access.md (+271-287)
- (modified) clang-tools-extra/docs/clang-tidy/checks/abseil/upgrade-duration-conversions.md (+21-21)
``````````diff
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-comparison.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-comparison.md
index 6df0514dec683..aab1f1d39d5f4 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-comparison.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-comparison.md
@@ -1,33 +1,33 @@
-.. title:: clang-tidy - abseil-duration-comparison
+```{title} clang-tidy - abseil-duration-comparison
+```
-abseil-duration-comparison
-==========================
+# abseil-duration-comparison
-Checks for comparisons which should be in the ``absl::Duration`` domain instead
+Checks for comparisons which should be in the `absl::Duration` domain instead
of the floating point or integer domains.
-N.B.: In cases where a ``Duration`` was being converted to an integer and then
-compared against a floating-point value, truncation during the ``Duration``
+N.B.: In cases where a `Duration` was being converted to an integer and then
+compared against a floating-point value, truncation during the `Duration`
conversion might yield a different result. In practice this is very rare, and
still indicates a bug which should be fixed.
Examples:
-.. code-block:: c++
+```cpp
+// Original - Comparison in the floating point domain
+double x;
+absl::Duration d;
+if (x < absl::ToDoubleSeconds(d)) ...
- // Original - Comparison in the floating point domain
- double x;
- absl::Duration d;
- if (x < absl::ToDoubleSeconds(d)) ...
+// Suggested - Compare in the absl::Duration domain instead
+if (absl::Seconds(x) < d) ...
- // Suggested - Compare in the absl::Duration domain instead
- if (absl::Seconds(x) < d) ...
+// Original - Comparison in the integer domain
+int x;
+absl::Duration d;
+if (x < absl::ToInt64Microseconds(d)) ...
- // Original - Comparison in the integer domain
- int x;
- absl::Duration d;
- if (x < absl::ToInt64Microseconds(d)) ...
-
- // Suggested - Compare in the absl::Duration domain instead
- if (absl::Microseconds(x) < d) ...
+// Suggested - Compare in the absl::Duration domain instead
+if (absl::Microseconds(x) < d) ...
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-conversion-cast.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-conversion-cast.md
index 05c11cddfd5f9..0e647214f4e12 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-conversion-cast.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-conversion-cast.md
@@ -1,31 +1,30 @@
-.. title:: clang-tidy - abseil-duration-conversion-cast
+```{title} clang-tidy - abseil-duration-conversion-cast
+```
-abseil-duration-conversion-cast
-===============================
+# abseil-duration-conversion-cast
-Checks for casts of ``absl::Duration`` conversion functions, and recommends
+Checks for casts of `absl::Duration` conversion functions, and recommends
the right conversion function instead.
Examples:
-.. code-block:: c++
+```cpp
+// Original - Cast from a double to an integer
+absl::Duration d;
+int i = static_cast<int>(absl::ToDoubleSeconds(d));
- // Original - Cast from a double to an integer
- absl::Duration d;
- int i = static_cast<int>(absl::ToDoubleSeconds(d));
+// Suggested - Use the integer conversion function directly.
+int i = absl::ToInt64Seconds(d);
- // Suggested - Use the integer conversion function directly.
- int i = absl::ToInt64Seconds(d);
+// Original - Cast from a double to an integer
+absl::Duration d;
+double x = static_cast<double>(absl::ToInt64Seconds(d));
- // Original - Cast from a double to an integer
- absl::Duration d;
- double x = static_cast<double>(absl::ToInt64Seconds(d));
-
- // Suggested - Use the integer conversion function directly.
- double x = absl::ToDoubleSeconds(d);
-
+// Suggested - Use the integer conversion function directly.
+double x = absl::ToDoubleSeconds(d);
+```
Note: In the second example, the suggested fix could yield a different result,
as the conversion to integer could truncate. In practice, this is very rare,
-and you should use ``absl::Trunc`` to perform this operation explicitly instead.
+and you should use `absl::Trunc` to perform this operation explicitly instead.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-division.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-division.md
index 40c12d464687d..beb38bd63ef2b 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-division.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-division.md
@@ -1,38 +1,37 @@
-.. title:: clang-tidy - abseil-duration-division
+```{title} clang-tidy - abseil-duration-division
+```
-abseil-duration-division
-========================
+# abseil-duration-division
-``absl::Duration`` arithmetic works like it does with integers. That means that
-division of two ``absl::Duration`` objects returns an ``int64`` with any
+`absl::Duration` arithmetic works like it does with integers. That means that
+division of two `absl::Duration` objects returns an `int64` with any
fractional component truncated toward 0.
-See `this link <https://github.com/abseil/abseil-cpp/blob/29ff6d4860070bf8fcbd39c8805d0c32d56628a3/absl/time/time.h#L137>`_
-for more information on arithmetic with ``absl::Duration``.
+See [this link](https://github.com/abseil/abseil-cpp/blob/29ff6d4860070bf8fcbd39c8805d0c32d56628a3/absl/time/time.h#L137)
+for more information on arithmetic with `absl::Duration`.
For example:
-.. code-block:: c++
+```cpp
+absl::Duration d = absl::Seconds(3.5);
+int64 sec1 = d / absl::Seconds(1); // Truncates toward 0.
+int64 sec2 = absl::ToInt64Seconds(d); // Equivalent to division.
+assert(sec1 == 3 && sec2 == 3);
- absl::Duration d = absl::Seconds(3.5);
- int64 sec1 = d / absl::Seconds(1); // Truncates toward 0.
- int64 sec2 = absl::ToInt64Seconds(d); // Equivalent to division.
- assert(sec1 == 3 && sec2 == 3);
-
- double dsec = d / absl::Seconds(1); // WRONG: Still truncates toward 0.
- assert(dsec == 3.0);
+double dsec = d / absl::Seconds(1); // WRONG: Still truncates toward 0.
+assert(dsec == 3.0);
+```
If you want floating-point division, you should use either the
-``absl::FDivDuration()`` function, or one of the unit conversion functions such
-as ``absl::ToDoubleSeconds()``. For example:
-
-.. code-block:: c++
-
- absl::Duration d = absl::Seconds(3.5);
- double dsec1 = absl::FDivDuration(d, absl::Seconds(1)); // GOOD: No truncation.
- double dsec2 = absl::ToDoubleSeconds(d); // GOOD: No truncation.
- assert(dsec1 == 3.5 && dsec2 == 3.5);
+`absl::FDivDuration()` function, or one of the unit conversion functions such
+as `absl::ToDoubleSeconds()`. For example:
+```cpp
+absl::Duration d = absl::Seconds(3.5);
+double dsec1 = absl::FDivDuration(d, absl::Seconds(1)); // GOOD: No truncation.
+double dsec2 = absl::ToDoubleSeconds(d); // GOOD: No truncation.
+assert(dsec1 == 3.5 && dsec2 == 3.5);
+```
-This check looks for uses of ``absl::Duration`` division that is done in a
+This check looks for uses of `absl::Duration` division that is done in a
floating-point context, and recommends the use of a function that returns a
floating-point value.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-factory-scale.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-factory-scale.md
index cba5202957463..a2e73c2bb9616 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-factory-scale.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-factory-scale.md
@@ -1,35 +1,35 @@
-.. title:: clang-tidy - abseil-duration-factory-scale
+```{title} clang-tidy - abseil-duration-factory-scale
+```
-abseil-duration-factory-scale
-=============================
+# abseil-duration-factory-scale
-Checks for cases where arguments to ``absl::Duration`` factory functions are
+Checks for cases where arguments to `absl::Duration` factory functions are
scaled internally and could be changed to a different factory function. This
check also looks for arguments with a zero value and suggests using
-``absl::ZeroDuration()`` instead.
+`absl::ZeroDuration()` instead.
Examples:
-.. code-block:: c++
+```cpp
+// Original - Internal multiplication.
+int x;
+absl::Duration d = absl::Seconds(60 * x);
- // Original - Internal multiplication.
- int x;
- absl::Duration d = absl::Seconds(60 * x);
+// Suggested - Use absl::Minutes instead.
+absl::Duration d = absl::Minutes(x);
- // Suggested - Use absl::Minutes instead.
- absl::Duration d = absl::Minutes(x);
+// Original - Internal division.
+int y;
+absl::Duration d = absl::Milliseconds(y / 1000.);
- // Original - Internal division.
- int y;
- absl::Duration d = absl::Milliseconds(y / 1000.);
+// Suggested - Use absl:::Seconds instead.
+absl::Duration d = absl::Seconds(y);
- // Suggested - Use absl:::Seconds instead.
- absl::Duration d = absl::Seconds(y);
+// Original - Zero-value argument.
+absl::Duration d = absl::Hours(0);
- // Original - Zero-value argument.
- absl::Duration d = absl::Hours(0);
-
- // Suggested = Use absl::ZeroDuration instead
- absl::Duration d = absl::ZeroDuration();
+// Suggested = Use absl::ZeroDuration instead
+absl::Duration d = absl::ZeroDuration();
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-subtraction.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-subtraction.md
index 3dfd326562084..3032a9118ace7 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-subtraction.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-subtraction.md
@@ -1,36 +1,35 @@
-.. title:: clang-tidy - abseil-duration-subtraction
+```{title} clang-tidy - abseil-duration-subtraction
+```
-abseil-duration-subtraction
-===========================
+# abseil-duration-subtraction
Checks for cases where subtraction should be performed in the
-``absl::Duration`` domain. When subtracting two values, and the first one is
-known to be a conversion from ``absl::Duration``, we can infer that the second
-should also be interpreted as an ``absl::Duration``, and make that inference
+`absl::Duration` domain. When subtracting two values, and the first one is
+known to be a conversion from `absl::Duration`, we can infer that the second
+should also be interpreted as an `absl::Duration`, and make that inference
explicit.
Examples:
-.. code-block:: c++
+```cpp
+// Original - Subtraction in the double domain
+double x;
+absl::Duration d;
+double result = absl::ToDoubleSeconds(d) - x;
- // Original - Subtraction in the double domain
- double x;
- absl::Duration d;
- double result = absl::ToDoubleSeconds(d) - x;
+// Suggestion - Subtraction in the absl::Duration domain instead
+double result = absl::ToDoubleSeconds(d - absl::Seconds(x));
- // Suggestion - Subtraction in the absl::Duration domain instead
- double result = absl::ToDoubleSeconds(d - absl::Seconds(x));
+// Original - Subtraction of two Durations in the double domain
+absl::Duration d1, d2;
+double result = absl::ToDoubleSeconds(d1) - absl::ToDoubleSeconds(d2);
- // Original - Subtraction of two Durations in the double domain
- absl::Duration d1, d2;
- double result = absl::ToDoubleSeconds(d1) - absl::ToDoubleSeconds(d2);
+// Suggestion - Subtraction in the absl::Duration domain instead
+double result = absl::ToDoubleSeconds(d1 - d2);
+```
- // Suggestion - Subtraction in the absl::Duration domain instead
- double result = absl::ToDoubleSeconds(d1 - d2);
-
-
-Note: As with other ``clang-tidy`` checks, it is possible that multiple fixes
+Note: As with other `clang-tidy` checks, it is possible that multiple fixes
may overlap (as in the case of nested expressions), so not all occurrences can
be transformed in one run. In particular, this may occur for nested subtraction
-expressions. Running ``clang-tidy`` multiple times will find and fix these
+expressions. Running `clang-tidy` multiple times will find and fix these
overlaps.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-unnecessary-conversion.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-unnecessary-conversion.md
index 264c5d08b9d29..2d564550ebab5 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-unnecessary-conversion.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/duration-unnecessary-conversion.md
@@ -1,57 +1,57 @@
-.. title:: clang-tidy - abseil-duration-unnecessary-conversion
+```{title} clang-tidy - abseil-duration-unnecessary-conversion
+```
-abseil-duration-unnecessary-conversion
-======================================
+# abseil-duration-unnecessary-conversion
-Finds and fixes cases where ``absl::Duration`` values are being converted to
+Finds and fixes cases where `absl::Duration` values are being converted to
numeric types and back again.
Floating-point examples:
-.. code-block:: c++
+```cpp
+// Original - Conversion to double and back again
+absl::Duration d1;
+absl::Duration d2 = absl::Seconds(absl::ToDoubleSeconds(d1));
- // Original - Conversion to double and back again
- absl::Duration d1;
- absl::Duration d2 = absl::Seconds(absl::ToDoubleSeconds(d1));
+// Suggestion - Remove unnecessary conversions
+absl::Duration d2 = d1;
- // Suggestion - Remove unnecessary conversions
- absl::Duration d2 = d1;
+// Original - Division to convert to double and back again
+absl::Duration d2 = absl::Seconds(absl::FDivDuration(d1, absl::Seconds(1)));
- // Original - Division to convert to double and back again
- absl::Duration d2 = absl::Seconds(absl::FDivDuration(d1, absl::Seconds(1)));
-
- // Suggestion - Remove division and conversion
- absl::Duration d2 = d1;
+// Suggestion - Remove division and conversion
+absl::Duration d2 = d1;
+```
Integer examples:
-.. code-block:: c++
-
- // Original - Conversion to integer and back again
- absl::Duration d1;
- absl::Duration d2 = absl::Hours(absl::ToInt64Hours(d1));
+```cpp
+// Original - Conversion to integer and back again
+absl::Duration d1;
+absl::Duration d2 = absl::Hours(absl::ToInt64Hours(d1));
- // Suggestion - Remove unnecessary conversions
- absl::Duration d2 = d1;
+// Suggestion - Remove unnecessary conversions
+absl::Duration d2 = d1;
- // Original - Integer division followed by conversion
- absl::Duration d2 = absl::Seconds(d1 / absl::Seconds(1));
+// Original - Integer division followed by conversion
+absl::Duration d2 = absl::Seconds(d1 / absl::Seconds(1));
- // Suggestion - Remove division and conversion
- absl::Duration d2 = d1;
+// Suggestion - Remove division and conversion
+absl::Duration d2 = d1;
+```
Unwrapping scalar operations:
-.. code-block:: c++
-
- // Original - Multiplication by a scalar
- absl::Duration d1;
- absl::Duration d2 = absl::Seconds(absl::ToInt64Seconds(d1) * 2);
+```cpp
+// Original - Multiplication by a scalar
+absl::Duration d1;
+absl::Duration d2 = absl::Seconds(absl::ToInt64Seconds(d1) * 2);
- // Suggestion - Remove unnecessary conversion
- absl::Duration d2 = d1 * 2;
+// Suggestion - Remove unnecessary conversion
+absl::Duration d2 = d1 * 2;
+```
-Note: Converting to an integer and back to an ``absl::Duration`` might be a
+Note: Converting to an integer and back to an `absl::Duration` might be a
truncating operation if the value is not aligned to the scale of conversion.
In the rare case where this is the intended result, callers should use
-``absl::Trunc`` to truncate explicitly.
+`absl::Trunc` to truncate explicitly.
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/faster-strsplit-delimiter.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/faster-strsplit-delimiter.md
index b5b79d405bded..b870ca9a79b00 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/faster-strsplit-delimiter.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/faster-strsplit-delimiter.md
@@ -1,12 +1,12 @@
-.. title:: clang-tidy - abseil-faster-strsplit-delimiter
+```{title} clang-tidy - abseil-faster-strsplit-delimiter
+```
-abseil-faster-strsplit-delimiter
-================================
+# abseil-faster-strsplit-delimiter
-Finds instances of ``absl::StrSplit()`` or ``absl::MaxSplits()`` where the
+Finds instances of `absl::StrSplit()` or `absl::MaxSplits()` where the
delimiter is a single character string literal and replaces with a character.
The check will offer a suggestion to change the string literal into a
-character. It will also catch code using ``absl::ByAnyChar()`` for just a
+character. It will also catch code using `absl::ByAnyChar()` for just a
single character and will transform that into a single character as well.
These changes will give the same result, but using characters rather than
@@ -14,28 +14,28 @@ single character string literals is more efficient and readable.
Examples:
-.. code-block:: c++
+```cpp
+// Original - the argument is a string literal.
+for (auto piece : absl::StrSplit(str, "B")) {
- // Original - the argument is a string literal.
- for (auto piece : absl::StrSplit(str, "B")) {
+// Suggested - the argument is a character, which causes the more efficient
+// overload of absl::StrSplit() to be used.
+for (auto piece : absl::StrSplit(str, 'B')) {
- // Suggested - the argument is a character, which causes the more efficient
- // overload of absl::StrSplit() to be used.
- for (auto piece : absl::StrSplit(str, 'B')) {
+// Original - the argument is a string literal inside absl::ByAnyChar call.
+for (auto piece : absl::StrSplit(str, absl::ByAnyChar("B"))) {
- // Original - the argument is a string literal inside absl::ByAnyChar call.
- for (auto piece : absl::StrSplit(str, absl::ByAnyChar("B"))) {
+// Suggested - the argument is a character, which causes the more efficient
+// overload of absl::StrSplit() to be used and we do not need absl::ByAnyChar
+// anymore.
+for (auto piece : absl::StrSplit(str, 'B')) {
- // Suggested - the argument is a character, which causes the more efficient
- // overload of absl::StrSplit() to be used and we do not need absl::ByAnyChar
- // anymore.
- for (auto piece : absl::StrSplit(str, 'B')) {
+// Original - the argument is a string literal inside absl::MaxSplits call.
+for (auto piece : absl::StrSplit(str, absl::MaxSplits("B", 1))) {
- // Original - the argument is a string literal inside absl::MaxSplits call.
- for (auto piece : absl::StrSplit(str, absl::MaxSplits("B", 1))) {
-
- // Suggested - the argument is a character, which causes the more efficient
- // overload of absl::StrSplit() to be used.
- for (auto piece : absl::StrSplit(str, absl::MaxSplits('B', 1))) {
+// Suggested - the argument is a character, which causes the more efficient
+// overload of absl::StrSplit() to be used.
+for (auto piece : absl::StrSplit(str, absl::MaxSplits('B', 1))) {
+```
diff --git a/clang-tools-extra/docs/clang-tidy/checks/abseil/string-find-startswith.md b/clang-tools-extra/docs/clang-tidy/checks/abseil/string-find-startswith.md
index 41a7ab500d7ce..3913c2ac43a05 100644
--- a/clang-tools-extra/docs/clang-tidy/checks/abseil/string-find-startswith.md
+++ b/clang-tools-extra/docs/clang-tidy/checks/abseil/string-find-startswith.md
@@ -1,48 +1,48 @@
-.. title:: clang-tidy - abseil-string-find-startswith
+```{title} clang-tidy - abseil-string-find-startswith
+```
-abseil-string-find-startswith
-=============================
+# abseil-string-find-startswith
-Checks whether a ``std::string::find()`` or ``std::string::rfind()`` (and
-corresponding ``std::string_view`` methods) result is compared with 0, and
-suggests replacing with ``absl::StartsWith()``. This is both a readability and
+Checks whether a `std::string::find()` or `std::string::rfind()` (and
+corresponding `std::string_view` methods) result is compared with 0, and
+suggests replacing with `absl::StartsWith()`. This is both a readability and
performance issue.
-``starts_with`` was added as a built-in function on those types in C++20. If
-available, prefer enabling :doc:`modernize-use-starts-ends-with
+`starts_with` was added as a built-in function on those types in C++20. If
+available, prefer enabling {doc}`modernize-use-starts-ends-with
<../modernize/use-starts-ends-with>` instead of this check.
-.. code-block:: c++
-
- string s = "...";
- if (s.find("Hello World") == 0) { /* do something */ }
- if (s.rfind("Hello World", 0) ...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/212004
More information about the llvm-branch-commits
mailing list