Add AsyncValue documentation

[snapsl]

Make riverpod onboarding easier.

AsyncValue is a core feature of riverpod when we use AsyncNotifier / FutureProvider, but is not explained in the documentation. Currently new user have to look into the api reference or source code to get basic information.

The documentation should contain:

• what is AsyncValue
  • utiltiy class
  • AsyncData /AsyncLoading / AsyncError
• how to use AsyncValue
  • modifying an async value
  • .guard()
  • resolve async value (map / pattern matching / value / valueOrNull)

In case information is missing, feel free to add them.

If needed, I can contribute to the docs.

[rrousselGit]

Sounds like this overlaps with the API reference.

It's normal IMO that folks have to look at the API reference if they want docs about a very specific thing.

[snapsl]

Yes, it will overlap. But, since AsyncValue is exclusiv to riverpod and needed for FutureProvider / AsyncNotifier, a new user has no information about this concept. The documentation could give a small introduction to AsyncValue and how to use it. A detailed description of the individual methods that AsyncValue provides is of course part of the API reference.

[rrousselGit]

I don't like the idea of having an overlap with the API reference.

If we want to improve AsyncValue's docs, I'd rather update the API reference to have better docs. Then link the AsyncValue's dartdoc page better in the doc.

Duplicate content will get out of sync.

[snapsl]

If we want to improve AsyncValue's docs, I'd rather update the API reference to have better docs. Then link the AsyncValue's dartdoc page better in the doc.

Maybe it is possible to link the api reference with the documentation similar to how Signals does it.

[rrousselGit]

I'm planning on having a way to extract dartdoc and put it into the website.