Add @checkReturnValue annotation that requires callers to use the return value

[parren-google]

It would be very helpful on the .build/.rebuild methods of BuiltValue, for example.
Otherwise, one can easily forget the _built= part in

set foo(int val) => _built = _built.rebuild((b) => b..val = val);

Dart VM version: 2.2.1-dev.4.2+google3-v2.2.1.dev.4.2 (google3) on "linux_x64"

@davidmorgan fyi

[bwilkerson]

Do you see this as being a generally useful annotation, or is this specifically to catch a common error in the way BuiltValue is used?

If it's the latter, then this might want to be part of the checking that the built_value plugin performs.

If it's the former, then could you be a bit more specific about what you mean by "check" or "use"? In the example it means "assigned to a field", but if this is a general annotation it should probably include something more than that.

[parren-google]

This is more generic. For example, it can be used on methods that return error values which callers really should not ignore by accident. Similar to the discussion about not awaiting Future returns.

So there are two categories:

• methods returning values that should not be ignored (like errors)
• methods whose sole purpose is to produce a return value without side effects -> not using the return is always a strong smell

For the latter, I guess any pure method qualifies that doesn't use exceptions as a form of regular alternative exit. But I'm not suggesting that Dart auto-detect such methods. The author would have to annotate them. Such auto-detection would be a different thing to possibly look into.

[davidmorgan]

Java has https://errorprone.info/bugpattern/CheckReturnValue which is the same idea.

[pq]

See discussion in #58084; basic support for @useResult has landed.

Feedback (there) welcome!