diff options
Diffstat (limited to 'clang-tools-extra/docs')
| -rw-r--r-- | clang-tools-extra/docs/ReleaseNotes.rst | 6 | ||||
| -rw-r--r-- | clang-tools-extra/docs/clang-tidy/checks/list.rst | 1 | ||||
| -rw-r--r-- | clang-tools-extra/docs/clang-tidy/checks/modernize-use-nodiscard.rst | 77 |
3 files changed, 84 insertions, 0 deletions
diff --git a/clang-tools-extra/docs/ReleaseNotes.rst b/clang-tools-extra/docs/ReleaseNotes.rst index 706e83d21e9..f6cdc3efbdc 100644 --- a/clang-tools-extra/docs/ReleaseNotes.rst +++ b/clang-tools-extra/docs/ReleaseNotes.rst @@ -220,6 +220,12 @@ Improvements to clang-tidy Detects usage of the deprecated member types of ``std::ios_base`` and replaces those that have a non-deprecated equivalent. +- New :doc:`modernize-use-nodiscard + <clang-tidy/checks/modernize-use-nodiscard>` check. + + Adds ``[[nodiscard]]`` attributes (introduced in C++17) to member functions + to highlight at compile time which return values should not be ignored. + - New :doc:`readability-isolate-decl <clang-tidy/checks/readability-isolate-declaration>` check. diff --git a/clang-tools-extra/docs/clang-tidy/checks/list.rst b/clang-tools-extra/docs/clang-tidy/checks/list.rst index 633ce30e2ba..b4a60e76c8e 100644 --- a/clang-tools-extra/docs/clang-tidy/checks/list.rst +++ b/clang-tools-extra/docs/clang-tidy/checks/list.rst @@ -207,6 +207,7 @@ Clang-Tidy Checks modernize-use-emplace modernize-use-equals-default modernize-use-equals-delete + modernize-use-nodiscard modernize-use-noexcept modernize-use-nullptr modernize-use-override diff --git a/clang-tools-extra/docs/clang-tidy/checks/modernize-use-nodiscard.rst b/clang-tools-extra/docs/clang-tidy/checks/modernize-use-nodiscard.rst new file mode 100644 index 00000000000..88507e8e9ab --- /dev/null +++ b/clang-tools-extra/docs/clang-tidy/checks/modernize-use-nodiscard.rst @@ -0,0 +1,77 @@ +.. title:: clang-tidy - modernize-use-nodiscard + +modernize-use-nodiscard +======================= + +Adds ``[[nodiscard]]`` attributes (introduced in C++17) to member functions in +order to highlight at compile time which return values should not be ignored. + +Member functions need to satisfy the following conditions to be considered by +this check: + - no ``[[nodiscard]]``, ``[[noreturn]]``, ``__attribute__((warn_unused_result))``, ``[[clang::warn_unused_result]]`` nor ``[[gcc::warn_unused_result]]`` attribute, + - non-void return type, + - non-template return types, + - const member function, + - non-variadic functions, + - no non-const reference parameters, + - no pointer parameters, + - no template parameters, + - no template function parameters, + - not be a member of a class with mutable member variables, + - no Lambdas, + - no conversion functions. + +Such functions have no means of altering any state or passing values other than +via the return type. Unless the member functions are altering state via some +external call (e.g. I/O). + +Example +------- + +.. code-block:: c++ + + bool empty() const; + bool empty(int i) const; + +transforms to: + +.. code-block:: c++ + + [[nodiscard] bool empty() const; + [[nodiscard] bool empty(int i) const; + +Options +------- + +.. option:: ReplacementString + +Specifies a macro to use instead of ``[[nodiscard]]``. This is useful when +maintaining source code that needs to compile with a pre-C++17 compiler. + +Example +^^^^^^^ + +.. code-block:: c++ + + bool empty() const; + bool empty(int i) const; + +transforms to: + +.. code-block:: c++ + + NO_DISCARD bool empty() const; + NO_DISCARD bool empty(int i) const; + +if the :option:`ReplacementString` option is set to `NO_DISCARD`. + +.. note:: + +If the :option:`ReplacementString` is not a C++ attribute, but instead a macro, +then that macro must be defined in scope or the fix-it will not be applied. + +.. note:: + + For alternative ``__attribute__`` syntax options to mark functions as + ``[[nodiscard]]`` in non-c++17 source code. + See https://clang.llvm.org/docs/AttributeReference.html#nodiscard-warn-unused-result |
