[clang-tidy] Adding a new modernize use nodiscard checker

Summary: Adds a checker to clang-tidy to warn when a non void const member function, taking only parameters passed by value or const reference could be marked as '[[nodiscard]]'

Patch by MyDeveloperDay.

Reviewers: alexfh, stephenkelly, curdeius, aaron.ballman, hokein, JonasToth

Reviewed By: curdeius, JonasToth

Subscribers: Eugene.Zelenko, lefticus, lebedev.ri, mgorny, xazax.hun, cfe-commits

Tags: #clang-tools-extra

Differential Revision: https://reviews.llvm.org/D55433

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