Provide better documentation/examples for `provideDummy`/`provideDummyBuilder`

[jamesderlin]

Two people on StackOverflow coincidentally today got confused by the error message about provideDummy/provideDummyBuilder:

• https://stackoverflow.com/questions/77205684/#comment136107698_77205684
• https://stackoverflow.com/q/77206987/

The API documentation for provideDummy and for provideDummyBuilder could be improved:

• Explain why (or in what situations) they're necessary.
• Provide examples on usage.
• It also would be nice if the error message itself provided an URL for more information.

Additionally, ProvideDummyBuilder takes a DummyBuilder<T> argument, but that typedef is not exported and therefore is not included in the API documentation. The only way to determine what DummyBuilder is from the docs is to inspect the implementation of ProvideDummy.

[jamesderlin]

Additionally:

• https://stackoverflow.com/q/77272908/
• https://stackoverflow.com/q/77814642/
• https://stackoverflow.com/q/77993902/

[DerJojo11]

THANK YOU!

Struggled the last hour why and how I fix this error. Don't get why I have to do this now (freshly updated).

So I give a thumbs up to the question: why do we need this now?

[jamesderlin]

@DerJojo11 Let's say you have:

class Bar {}

class Foo {
  Bar method() => Bar();
}

and now you want to mock Foo. With @GenerateNiceMocks, the generated implementation for MockFoo needs method() to be able to return something. It can't return null since the return type is non-nullable. Normally code generation will generate something like class FakeBar extends Fake implements Bar {}, and then MockFoo's method implementation can construct and return a FakeBar instance.

However, if Bar is sealed, then it cannot be extended nor implemented, disallowing the generation of FakeBar. Therefore Mockito can't generate a default value for a Bar on its own, and it needs users to specify what default value to use.