Author: Zeyi Xu Date: 2026-09-07T18:09:15+08:00 New Revision: 76a090dfd9d81761087453de3ada2eb7ff2528f7
URL: https://github.com/llvm/llvm-project/commit/76a090dfd9d81761087453de3ada2eb7ff2528f7 DIFF: https://github.com/llvm/llvm-project/commit/76a090dfd9d81761087453de3ada2eb7ff2528f7.diff LOG: [clang-tidy][docs] Rewrite readability check docs to Markdown [1/5] (#221447) Tracking issue: #201242 See the [migration guide] for more information. [migration guide]: https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines This is the first part of rewriting check documentations in readability module from reST to MyST Markdown. AI Usage: This was prepared with rnk's fork of rst2myst and GPT5.6-assisted cleanup. I manually verified that the documentation renders as expected. Preview site: https://broken.life/llvm-staging/readability-markdown-port/index.html --------- Co-authored-by: EugeneZelenko <[email protected]> Added: Modified: clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md Removed: ################################################################################ diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md b/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md index f8df02dd4460e..5d757ae88cae1 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/ambiguous-smartptr-reset-call.md @@ -1,62 +1,64 @@ -.. title:: clang-tidy - readability-ambiguous-smartptr-reset-call +```{title} clang-tidy - readability-ambiguous-smartptr-reset-call +``` -readability-ambiguous-smartptr-reset-call -========================================= +# readability-ambiguous-smartptr-reset-call -Finds potentially erroneous calls to ``reset`` method on smart pointers when -the pointee type also has a ``reset`` method. Having a ``reset`` method in +Finds potentially erroneous calls to `reset` method on smart pointers when +the pointee type also has a `reset` method. Having a `reset` method in both classes makes it easy to accidentally make the pointer null when intending to reset the underlying object. -.. code-block:: c++ +```c++ +struct Resettable { + void reset() { /* Own reset logic */ } +}; - struct Resettable { - void reset() { /* Own reset logic */ } - }; +auto ptr = std::make_unique<Resettable>(); - auto ptr = std::make_unique<Resettable>(); - - ptr->reset(); // Calls underlying reset method - ptr.reset(); // Makes the pointer null +ptr->reset(); // Calls underlying reset method +ptr.reset(); // Makes the pointer null +``` Both calls are valid C++ code, but the second one might not be what the developer intended, as it destroys the pointed-to object rather than resetting its state. It's easy to make such a typo because the diff erence between -``.`` and ``->`` is really small. +`.` and `->` is really small. The recommended approach is to make the intent explicit by using either member access or direct assignment: -.. code-block:: c++ - - std::unique_ptr<Resettable> ptr = std::make_unique<Resettable>(); +```c++ +std::unique_ptr<Resettable> ptr = std::make_unique<Resettable>(); - (*ptr).reset(); // Clearly calls underlying reset method - ptr = nullptr; // Clearly makes the pointer null +(*ptr).reset(); // Clearly calls underlying reset method +ptr = nullptr; // Clearly makes the pointer null +``` The default smart pointers and classes that are considered are -``std::unique_ptr``, ``std::shared_ptr``, ``boost::shared_ptr``. To specify -other smart pointers or other classes use the :option:`SmartPointers` option. - - -.. note:: - - The check may emit invalid fix-its and misleading warning messages when - specifying custom smart pointers or other classes in the - :option:`SmartPointers` option. For example, ``boost::scoped_ptr`` does not - have an ``operator=`` which makes fix-its invalid. - -.. note:: - - Automatic fix-its are enabled only if :program:`clang-tidy` is invoked with - the `--fix-notes` option. - - -Options -------- - -.. option:: SmartPointers - - Semicolon-separated list of fully qualified class names of custom smart - pointers. Default value is `::std::unique_ptr;::std::shared_ptr; - ::boost::shared_ptr`. +`std::unique_ptr`, `std::shared_ptr`, `boost::shared_ptr`. To specify +other smart pointers or other classes use the +[`SmartPointers`](#readability-ambiguous-smartptr-reset-call-smart-pointers) +option. + +```{note} +The check may emit invalid fix-its and misleading warning messages when +specifying custom smart pointers or other classes in the +[`SmartPointers`](#readability-ambiguous-smartptr-reset-call-smart-pointers) +option. For example, `boost::scoped_ptr` does not +have an `operator=` which makes fix-its invalid. +``` + +```{note} +Automatic fix-its are enabled only if {program}`clang-tidy` is invoked with +the `--fix-notes` option. +``` + +## Options + +(readability-ambiguous-smartptr-reset-call-smart-pointers)= + +```{option} SmartPointers +Semicolon-separated list of fully qualified class names of custom smart +pointers. Default is +`::std::unique_ptr;::std::shared_ptr;::boost::shared_ptr`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md index b07958188d313..6733a2bf9bdde 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-return-with-void-value.md @@ -1,51 +1,49 @@ -.. title:: clang-tidy - readability-avoid-return-with-void-value +```{title} clang-tidy - readability-avoid-return-with-void-value +``` -readability-avoid-return-with-void-value -======================================== +# readability-avoid-return-with-void-value -Finds return statements with ``void`` values used within functions with -``void`` result types. +Finds return statements with `void` values used within functions with +`void` result types. -A function with a ``void`` return type is intended to perform a task without +A function with a `void` return type is intended to perform a task without producing a return value. Return statements with expressions could lead to confusion and may miscommunicate the function's intended behavior. Example: -.. code-block:: +``` +void g(); +void f() { + // ... + return g(); +} +``` - void g(); - void f() { - // ... - return g(); - } - -In a long function body, the ``return`` statement suggests that the function -returns a value. However, ``return g();`` is a combination of two statements +In a long function body, the `return` statement suggests that the function +returns a value. However, `return g();` is a combination of two statements that should be written as -.. code-block:: - - g(); - return; +``` +g(); +return; +``` -to make clear that ``g()`` is called and immediately afterwards the function +to make clear that `g()` is called and immediately afterwards the function returns (nothing). -In C, the same issue is detected by the compiler if the ``-Wpedantic`` mode +In C, the same issue is detected by the compiler if the `-Wpedantic` mode is enabled. -Options -------- - -.. option:: IgnoreMacros - - The value `false` specifies that return statements expanded - from macros are not checked. The default value is `true`. +## Options -.. option:: StrictMode +```{option} IgnoreMacros +When `false`, return statements expanded from macros are not checked. +Default is `true`. +``` - The value `false` specifies that a direct return statement shall - be excluded from the analysis if it is the only statement not - contained in a block, like ``if (cond) return g();``. The default - value is `true`. +```{option} StrictMode +When `false`, a direct return statement is excluded from the analysis if it is +the only statement not contained in a block, like +`if (cond) return g();`. Default is `true`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md index ce3bfaffac380..87e814a085227 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/avoid-unconditional-preprocessor-if.md @@ -1,32 +1,32 @@ -.. title:: clang-tidy - readability-avoid-unconditional-preprocessor-if +```{title} clang-tidy - readability-avoid-unconditional-preprocessor-if +``` -readability-avoid-unconditional-preprocessor-if -=============================================== +# readability-avoid-unconditional-preprocessor-if Finds code blocks that are constantly enabled or disabled in preprocessor -directives by analyzing ``#if`` conditions, such as ``#if 0`` and ``#if 1``, +directives by analyzing `#if` conditions, such as `#if 0` and `#if 1`, etc. -.. code-block:: c++ +```c++ +#if 0 + // some disabled code +#endif - #if 0 - // some disabled code - #endif +#if 1 + // some enabled code that can be disabled manually +#endif +``` - #if 1 - // some enabled code that can be disabled manually - #endif - -Unconditional preprocessor directives, such as ``#if 0`` for disabled code -and ``#if 1`` for enabled code, can lead to dead code and always enabled code, +Unconditional preprocessor directives, such as `#if 0` for disabled code +and `#if 1` for enabled code, can lead to dead code and always enabled code, respectively. Dead code can make understanding the codebase more diff icult, hinder readability, and may be a sign of unfinished functionality or abandoned features. This can cause maintenance issues, confusion for future developers, and potential compilation problems. As a solution for both cases, consider using preprocessor macros or defines, -like ``#ifdef DEBUGGING_ENABLED``, to control code enabling or disabling. +like `#ifdef DEBUGGING_ENABLED`, to control code enabling or disabling. This approach provides better coordination and flexibility when working with diff erent parts of the codebase. Alternatively, you can comment out the entire -code using ``/* */`` block comments and add a hint, such as ``@todo``, +code using `/* */` block comments and add a hint, such as `@todo`, to indicate future actions. diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md b/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md index 2c0816591eb98..a8e4e62ace963 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/braces-around-statements.md @@ -1,38 +1,37 @@ -.. title:: clang-tidy - readability-braces-around-statements +```{title} clang-tidy - readability-braces-around-statements +``` -readability-braces-around-statements -==================================== +# readability-braces-around-statements `google-readability-braces-around-statements` redirects here as an alias for this check. -Checks that bodies of ``if`` statements and loops (``for``, ``do while``, and -``while``) are inside braces. +Checks that bodies of `if` statements and loops (`for`, `do while`, and +`while`) are inside braces. Before: -.. code-block:: c++ - - if (condition) - statement; +```c++ +if (condition) + statement; +``` After: -.. code-block:: c++ - - if (condition) { - statement; - } - -Options -------- +```c++ +if (condition) { + statement; +} +``` -.. option:: ShortStatementLines +## Options - Defines the minimal number of lines that the statement should have in order - to trigger this check. +```{option} ShortStatementLines +Defines the minimal number of lines that the statement should have in order +to trigger this check. - The number of lines is counted from the end of condition or initial keyword - (``do``/``else``) until the last line of the inner statement. Default value - `0` means that braces will be added to all statements (not having them - already). +The number of lines is counted from the end of condition or initial keyword +(`do`/`else`) until the last line of the inner statement. A value of `0` means +that braces will be added to all statements that do not already have them. +Default is `0`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md b/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md index ec81d46750d44..1d86ccbac2cce 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/const-return-type.md @@ -1,35 +1,33 @@ -.. title:: clang-tidy - readability-const-return-type +```{title} clang-tidy - readability-const-return-type +``` -readability-const-return-type -============================= +# readability-const-return-type -Checks for functions with a ``const``-qualified return type and recommends -removal of the ``const`` keyword. Such use of `const` is usually superfluous, +Checks for functions with a `const`-qualified return type and recommends +removal of the `const` keyword. Such use of `const` is usually superfluous, and can prevent valuable compiler optimizations. Does not (yet) fix trailing return types. Examples: -.. code-block:: c++ - - const int foo(); - const Clazz foo(); - Clazz *const foo(); +```c++ +const int foo(); +const Clazz foo(); +Clazz *const foo(); +``` Note that this applies strictly to top-level qualification, which excludes pointers or references to const values. For example, these are fine: -.. code-block:: c++ - - const int* foo(); - const int& foo(); - const Clazz* foo(); - - -Options -------- +```c++ +const int* foo(); +const int& foo(); +const Clazz* foo(); +``` -.. option:: IgnoreMacros +## Options - If set to `true`, the check will not give warnings inside macros. Default - is `true`. +```{option} IgnoreMacros +When `true`, the check will not give warnings inside macros. +Default is `true`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md b/clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md index 120d360ab5841..bd12584376cb4 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/container-contains.md @@ -1,34 +1,32 @@ -.. title:: clang-tidy - readability-container-contains +```{title} clang-tidy - readability-container-contains +``` -readability-container-contains -============================== +# readability-container-contains -Finds usages of ``container.count()`` and -``container.find() == container.end()`` which should be replaced by a call to -the ``container.contains()`` method. +Finds usages of `container.count()` and +`container.find() == container.end()` which should be replaced by a call to +the `container.contains()` method. Whether an element is contained inside a container should be checked with -``contains`` instead of ``count``/``find`` because ``contains`` conveys the +`contains` instead of `count`/`find` because `contains` conveys the intent more clearly. Furthermore, for containers which permit multiple entries -per key (``multimap``, ``multiset``, ...), ``contains`` is more efficient than -``count`` because ``count`` has to do unnecessary additional work. +per key (`multimap`, `multiset`, ...), `contains` is more efficient than +`count` because `count` has to do unnecessary additional work. Examples: -====================================== ===================================== -Initial expression Result --------------------------------------- ------------------------------------- -``myMap.find(x) == myMap.end()`` ``!myMap.contains(x)`` -``myMap.find(x) != myMap.end()`` ``myMap.contains(x)`` -``myStr.find(x) != std::string::npos`` ``myStr.contains(x)`` -``if (myMap.count(x))`` ``if (myMap.contains(x))`` -``bool exists = myMap.count(x)`` ``bool exists = myMap.contains(x)`` -``bool exists = myMap.count(x) > 0`` ``bool exists = myMap.contains(x)`` -``bool exists = myMap.count(x) >= 1`` ``bool exists = myMap.contains(x)`` -``bool missing = myMap.count(x) == 0`` ``bool missing = !myMap.contains(x)`` -====================================== ===================================== +| Initial expression | Result | +|--------------------------------------|-------------------------------------| +| `myMap.find(x) == myMap.end()` | `!myMap.contains(x)` | +| `myMap.find(x) != myMap.end()` | `myMap.contains(x)` | +| `myStr.find(x) != std::string::npos` | `myStr.contains(x)` | +| `if (myMap.count(x))` | `if (myMap.contains(x))` | +| `bool exists = myMap.count(x)` | `bool exists = myMap.contains(x)` | +| `bool exists = myMap.count(x) > 0` | `bool exists = myMap.contains(x)` | +| `bool exists = myMap.count(x) >= 1` | `bool exists = myMap.contains(x)` | +| `bool missing = myMap.count(x) == 0` | `bool missing = !myMap.contains(x)` | -This check will apply to any class that has a ``contains`` method, notably -including ``std::set``, ``std::unordered_set``, ``std::map``, and -``std::unordered_map`` as of C++20, and ``std::string`` and -``std::string_view`` as of C++23. +This check will apply to any class that has a `contains` method, notably +including `std::set`, `std::unordered_set`, `std::map`, and +`std::unordered_map` as of C++20, and `std::string` and +`std::string_view` as of C++23. diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md b/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md index 70b05f498d804..89b5f9fbbc886 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/container-size-empty.md @@ -1,37 +1,35 @@ -.. title:: clang-tidy - readability-container-size-empty +```{title} clang-tidy - readability-container-size-empty +``` -readability-container-size-empty -================================ +# readability-container-size-empty +Checks whether a call to the `size()`/`length()` method or the +`std::size()` free function can be replaced with a call to `empty()`. -Checks whether a call to the ``size()``/``length()`` method or the -``std::size()`` free function can be replaced with a call to ``empty()``. - -The emptiness of a container should be checked using the ``empty()`` method -instead of the ``size()``/``length()`` method or ``std::size()``. It shows -clearer intent to use ``empty()``. Furthermore some containers (for example, a -``std::forward_list``) may implement the ``empty()`` method but not implement -the ``size()`` or ``length()`` method. Using ``empty()`` whenever possible +The emptiness of a container should be checked using the `empty()` method +instead of the `size()`/`length()` method or `std::size()`. It shows +clearer intent to use `empty()`. Furthermore some containers (for example, a +`std::forward_list`) may implement the `empty()` method but not implement +the `size()` or `length()` method. Using `empty()` whenever possible makes it easier to switch to another container in the future. -The check issues warning if a container has ``empty()`` and ``size()`` or -``length()`` methods matching following signatures: - -.. code-block:: c++ +The check issues warning if a container has `empty()` and `size()` or +`length()` methods matching following signatures: - size_type size() const; - size_type length() const; - bool empty() const; +```c++ +size_type size() const; +size_type length() const; +bool empty() const; +``` `size_type` can be any kind of integer type. -Options -------- - -.. option:: ExcludedComparisonTypes +## Options - A semicolon-separated list of regular expressions matching class names for - which the check will ignore comparisons of objects with default-constructed - objects of the same type. If a class is listed here, the check will not - suggest using ``empty()`` instead of such comparisons for objects of that - class. Default value is: `::std::array`. +```{option} ExcludedComparisonTypes +A semicolon-separated list of regular expressions matching class names for +which the check will ignore comparisons of objects with default-constructed +objects of the same type. If a class is listed here, the check will not +suggest using `empty()` instead of such comparisons for objects of that +class. Default is `::std::array`. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md b/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md index 28a4991a922f8..5ff274157eff7 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/duplicate-include.md @@ -1,44 +1,43 @@ -.. title:: clang-tidy - readability-duplicate-include +```{title} clang-tidy - readability-duplicate-include +``` -readability-duplicate-include -============================= +# readability-duplicate-include -Looks for duplicate includes and removes them. The check maintains a list of -included files and looks for duplicates. If a macro is defined or undefined +Looks for duplicate includes and removes them. The check maintains a list of +included files and looks for duplicates. If a macro is defined or undefined then the list of included files is cleared. Examples: -.. code-block:: c++ - - #include <memory> - #include <vector> - #include <memory> +```c++ +#include <memory> +#include <vector> +#include <memory> +``` becomes -.. code-block:: c++ - - #include <memory> - #include <vector> +```c++ +#include <memory> +#include <vector> +``` Because of the intervening macro definitions, this code remains unchanged: -.. code-block:: c++ - - #undef NDEBUG - #include "assertion.h" - // ...code with assertions enabled - - #define NDEBUG - #include "assertion.h" - // ...code with assertions disabled +```c++ +#undef NDEBUG +#include "assertion.h" +// ...code with assertions enabled -Options -------- +#define NDEBUG +#include "assertion.h" +// ...code with assertions disabled +``` -.. option:: IgnoredFilesList +## Options - A semicolon-separated list of regular expressions or filenames that are - allowed to be included multiple times without diagnostics. Matching is - performed against the textual include name. Default is an empty string. +```{option} IgnoredFilesList +A semicolon-separated list of regular expressions or filenames that are +allowed to be included multiple times without diagnostics. Matching is +performed against the textual include name. Default is an empty string. +``` diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md b/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md index 569fa24d81c49..b6edb8ee2e419 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/else-after-return.md @@ -1,90 +1,85 @@ -.. title:: clang-tidy - readability-else-after-return +```{title} clang-tidy - readability-else-after-return +``` -readability-else-after-return -============================= +# readability-else-after-return -`LLVM Coding Standards <https://llvm.org/docs/CodingStandards.html>`_ advises to +[LLVM Coding Standards](https://llvm.org/docs/CodingStandards.html) advises to reduce indentation where possible and where it makes understanding code easier. Early exit is one of the suggested enforcements of that. Please do not use -``else`` or ``else if`` after something that interrupts control flow - like -``return``, ``break``, ``continue``, ``throw``. +`else` or `else if` after something that interrupts control flow - like +`return`, `break`, `continue`, `throw`. The following piece of code illustrates how the check works. This piece of code: -.. code-block:: c++ - - void foo(int Value) { - int Local = 0; - for (int i = 0; i < 42; i++) { - if (Value == 1) { - return; - } else { - Local++; - } - - if (Value == 2) - continue; - else - Local++; - - if (Value == 3) { - throw 42; - } else { - Local++; - } - } +```c++ +void foo(int Value) { + int Local = 0; + for (int i = 0; i < 42; i++) { + if (Value == 1) { + return; + } else { + Local++; } + if (Value == 2) + continue; + else + Local++; -Would be transformed into: - -.. code-block:: c++ - - void foo(int Value) { - int Local = 0; - for (int i = 0; i < 42; i++) { - if (Value == 1) { - return; - } - Local++; - - if (Value == 2) - continue; - Local++; - - if (Value == 3) { - throw 42; - } - Local++; - } + if (Value == 3) { + throw 42; + } else { + Local++; } + } +} +``` -Options -------- - -.. option:: WarnOnUnfixable - - When `true`, emit a warning for cases where the check can't output a - Fix-It. These can occur with declarations inside the ``else`` branch that - would have an extended lifetime if the ``else`` branch was removed. - Default value is `true`. - -.. option:: WarnOnConditionVariables +Would be transformed into: - When `true`, the check will attempt to refactor a variable defined inside - the condition of the ``if`` statement that is used in the ``else`` branch - defining them just before the ``if`` statement. This can only be done if - the ``if`` statement is the last statement in its parent's scope. - Default value is `true`. +```c++ +void foo(int Value) { + int Local = 0; + for (int i = 0; i < 42; i++) { + if (Value == 1) { + return; + } + Local++; + if (Value == 2) + continue; + Local++; -LLVM alias ----------- + if (Value == 3) { + throw 42; + } + Local++; + } +} +``` + +## Options + +```{option} WarnOnUnfixable +When `true`, emit a warning for cases where the check can't output a +fix-it. These can occur with declarations inside the `else` branch that +would have an extended lifetime if the `else` branch was removed. +Default is `true`. +``` + +```{option} WarnOnConditionVariables +When `true`, the check will attempt to refactor a variable defined inside +the condition of the `if` statement that is used in the `else` branch +defining them just before the `if` statement. This can only be done if +the `if` statement is the last statement in its parent's scope. +Default is `true`. +``` + +## LLVM alias There is an alias of this check called llvm-else-after-return. -In that version the options :option:`WarnOnUnfixable` and -:option:`WarnOnConditionVariables` are both set to `false` by default. +In that version the options {option}`WarnOnUnfixable` and +{option}`WarnOnConditionVariables` are both set to `false` by default. -This check helps to enforce this `LLVM Coding Standards recommendation -<https://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return>`_. +This check helps to enforce this [LLVM Coding Standards recommendation](https://llvm.org/docs/CodingStandards.html#don-t-use-else-after-a-return). diff --git a/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md b/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md index 8ca8ee7fe3569..aec3af8c11eec 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md +++ b/clang-tools-extra/docs/clang-tidy/checks/readability/enum-initial-value.md @@ -1,7 +1,7 @@ -.. title:: clang-tidy - readability-enum-initial-value +```{title} clang-tidy - readability-enum-initial-value +``` -readability-enum-initial-value -============================== +# readability-enum-initial-value Enforces consistent style for enumerators' initialization, covering three styles: none, first only, or all initialized explicitly. @@ -12,100 +12,97 @@ enumerators that obtain their integer representation implicitly. The following three cases are accepted: -#. **No** enumerators are explicit initialized. -#. Exactly **the first** enumerator is explicit initialized. -#. **All** enumerators are explicit initialized. - -.. code-block:: c++ - - enum A { // (1) Valid, none of enumerators are initialized. - a0, - a1, - a2, - }; - - enum B { // (2) Valid, the first enumerator is initialized. - b0 = 0, - b1, - b2, - }; - - enum C { // (3) Valid, all of enumerators are initialized. - c0 = 0, - c1 = 1, - c2 = 2, - }; - - enum D { // warning: initial values in enum 'D' are not consistent, - // consider explicit initialization of all, none or only - // the first enumerator - d0 = 0, - d1, // note: uninitialized enumerator 'd1' defined here - d2 = 2, - }; - - enum E { // warning: initial values in enum 'E' are not consistent, - // consider explicit initialization of all, none or only - // the first enumerator - e0 = 0, - e1, // note: uninitialized enumerator 'e1' defined here - e2 = 2, - e3, // note: uninitialized enumerator 'e3' defined here - // Dangerous, as the numeric values of e3 and e5 are both 3, - // and this is not explicitly visible in the code! - e4 = 2, - e5, // note: uninitialized enumerator 'e5' defined here - }; - -This check corresponds to the CERT C Coding Standard recommendation `INT09-C. Ensure enumeration constants map to unique values -<https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/integers-int/int09-c/>`_. +1. **No** enumerators are explicit initialized. +2. Exactly **the first** enumerator is explicit initialized. +3. **All** enumerators are explicit initialized. + +```c++ +enum A { // (1) Valid, none of enumerators are initialized. + a0, + a1, + a2, +}; + +enum B { // (2) Valid, the first enumerator is initialized. + b0 = 0, + b1, + b2, +}; + +enum C { // (3) Valid, all of enumerators are initialized. + c0 = 0, + c1 = 1, + c2 = 2, +}; + +enum D { // warning: initial values in enum 'D' are not consistent, + // consider explicit initialization of all, none or only + // the first enumerator + d0 = 0, + d1, // note: uninitialized enumerator 'd1' defined here + d2 = 2, +}; + +enum E { // warning: initial values in enum 'E' are not consistent, + // consider explicit initialization of all, none or only + // the first enumerator + e0 = 0, + e1, // note: uninitialized enumerator 'e1' defined here + e2 = 2, + e3, // note: uninitialized enumerator 'e3' defined here + // Dangerous, as the numeric values of e3 and e5 are both 3, + // and this is not explicitly visible in the code! + e4 = 2, + e5, // note: uninitialized enumerator 'e5' defined here +}; +``` + +This check corresponds to the CERT C Coding Standard recommendation [INT09-C. Ensure enumeration constants map to unique values](https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/integers-int/int09-c/). `cert-int09-c` redirects here as an alias of this check. -Options -------- - -.. option:: AllowExplicitZeroFirstInitialValue - - If set to `false`, the first enumerator must not be explicitly initialized to - a literal ``0``. - Default is `true`. - - .. code-block:: c++ - - enum F { - f0 = 0, // Not allowed if AllowExplicitZeroFirstInitialValue is false. - f1, - f2, - }; - - -.. option:: AllowExplicitSequentialInitialValues - - If set to `false`, explicit initialization to sequential values are not - allowed. - Default is `true`. - - .. code-block:: c++ - - enum G { - g0 = 1, // Not allowed if AllowExplicitSequentialInitialValues is false. - g1 = 2, - g2 = 3, - }; - -.. option:: AllowReferencedInitialValues - - If set to `true`, enumerators initialized by referencing another enumerator - in the same enum are allowed, and the remaining enumerators are checked for - consistency. This implements the `INT09-C-EX1` exception from the CERT C - Coding Standard. - Default is `false`. - - .. code-block:: c++ - - enum H { - h0, - h1, - h2 = h1, // Allowed if AllowReferencedInitialValues is true. - }; +## Options + +````{option} AllowExplicitZeroFirstInitialValue +When `false`, the first enumerator must not be explicitly initialized to +a literal `0`. +Default is `true`. + +```c++ +enum F { + f0 = 0, // Not allowed if AllowExplicitZeroFirstInitialValue is false. + f1, + f2, +}; +``` +```` + +````{option} AllowExplicitSequentialInitialValues +When `false`, explicit initialization to sequential values are not +allowed. +Default is `true`. + +```c++ +enum G { + g0 = 1, // Not allowed if AllowExplicitSequentialInitialValues is false. + g1 = 2, + g2 = 3, +}; +``` +```` + +````{option} AllowReferencedInitialValues +When `true`, enumerators initialized by referencing another enumerator +in the same enum are allowed, and the remaining enumerators are checked for +consistency. This implements the `INT09-C-EX1` exception from the CERT C +Coding Standard. +Default is `false`. + +```c++ +enum H { + h0, + h1, + h2 = h1, // Allowed if AllowReferencedInitialValues is true. +}; +``` +```` _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
