[clang-tidy] Wrong `modernize-use-nodiscard` warning when function returns a type marked as `[[nodiscard]]`

[fmun]

clang-tidy 21.1.3 erroneously reports

warning: function '...' should be marked [[nodiscard]] [modernize-use-nodiscard]

even though the function's return type is a class marked with [[nodiscard]].

Example:

#include <optional>

template<typename T>
class [[nodiscard]] MayBe
{
public:
	MayBe() = default;
	MayBe(const T& t) : _value(t) {};
    [[nodiscard]] bool HasValue()const { return _value.has_value(); };
    [[nodiscard]] const auto& operator*()const { return *_value; };
private:
    std::optional<T> _value;
};

class X
{
public:
    MayBe<int> divide(int x, int y) const;
};

clang-tidy was called with -checks=modernize-use-nodiscard and returns this:

<source>:18:5: warning: function 'divide' should be marked [[nodiscard]] [modernize-use-nodiscard]
18 |     MayBe<int> divide(int x, int y) const;
   |     ^
   |     [[nodiscard]] 
  1 warning generated.

https://godbolt.org/z/xKhEbx5nY

[llvmbot]

@llvm/issue-subscribers-clang-tidy

Author: None (fmun)

Details

`clang-tidy` 21.1.3 erroneously reports

> warning: function '...' should be marked [[nodiscard]] [modernize-use-nodiscard]

even though the function's return type is a class marked with [[nodiscard]].

Example:

#include <optional>

template<typename T>
class [[nodiscard]] MayBe
{
public:
	MayBe() = default;
	MayBe(const T& t) : _value(t) {};
    [[nodiscard]] bool HasValue()const { return _value.has_value(); };
    [[nodiscard]] const auto& operator*()const { return *_value; };
private:
    std::optional<T> _value;
};

class X
{
public:
    MayBe<int> divide(int x, int y) const;
};

clang-tidy was called with -checks=modernize-use-nodiscard and returns this:

<source>:18:5: warning: function 'divide' should be marked [[nodiscard]] [modernize-use-nodiscard]
18 |     MayBe<int> divide(int x, int y) const;
   |     ^
   |     [[nodiscard]] 
  1 warning generated.

https://godbolt.org/z/xKhEbx5nY

[localspook]

The check has code to handle [[nodiscard]] types already; it seems like this false positive only happens under very specific conditions. The return type must be a template, and that specific specialization of it must not be instantiated anywhere in the TU. And simply spelling out Template<int> in the return type does not cause an instantiation! When Clang sees that, it appears to only generate a "stub instantiation" of Template<int>, one with no WarnUnusedResultAttr. Writing out the body of the function seems to force a "full" instantiation, and the error goes away. Explicitly instantiating Template<int> does the same thing. You can see the experiments here. Look at lines 39 through 41 in the AST view; this is the "stub instantiation" I'm talking about.

I don't know what these stub instantiations are about. Maybe the problem is obvious to someone familiar with how templates are implemented? cc @erichkeane?