[pigeon] improve documentation

[bsutton]

I'm trying to convert an existing project to pigeon using a federated model and I'm find the documentation a little sparse.

https://pub.dev/packages?q=sounds

Googling pigeon and dart shows links like:
https://www.reddit.com/r/WTF/comments/86n6w2/so_a_pigeon_with_a_dart_in_the_head_just_landed/

:D

I've posted a question on stackoverflow but suspect that @ gaaclarke is the only authority on pigeon at the moment.
https://stackoverflow.com/questions/64037971/using-dart-pigeon-in-a-federated-model

It would be good to see documentation that directly speaks to the federated model.

The documentation mentions:

Api's should be defined as an abstract class with either HostApi() or FlutterApi() as metadata. The former being for procedures that are defined on the host platform and the latter for procedures that are defined in Dart.

However this statement leaves you guessing as to exactly what this are meant for.

I'm guessing that:
HostApi defines the set of calls the dart code makes into the platform specific code.
FlutterApi defines the set of calls the platform code can make back into the dart code.

(I now see that the api doco does provide more info on these but they are important enough that I think they should be documented on the readme).

It would be useful to see a discussion around migrating an existing channel based project to pigeon.

I note there is a PR for supporting async. This suggests that async calls are not currently supported.
It also suggests that more detailed documentation around calls into the platform needs to be created to explain what a sync vs async call into the platform should look like on both sides of the interface.

It may be a little early in the dev process but I would also like to see a section listing and discussing each of the generated files and their specific use.

[bsutton]

raised on the wrong repo :<