[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.

[gaaclarke]

Thanks for the good ideas. I think the documentation can be improved, for sure. If you want to see an example of using Pigeon with federated plugins, looking at video_player is the definitive example: https://github.com/flutter/plugins/tree/master/packages/video_player

As to the answers to some of your questions:

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.

That's correct.

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

I don't have that. I do have a working example from when I migrated video_player: flutter/plugins@c65bdd0#diff-1119d814fb92c6c6cff89707b50874ec

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.

I'll try to elaborate in the README. What I meant there is that implementors of the generated interface are expected to return synchronously, in contrast to platform channels which expect you to call a callback whenever you want. There is currently a PR out for a external contributor that is implementing this. There is a workaround now by just using a HostApi and FlutterApi and callback back and forth between them.

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.

I've limited the generate code to one source file per platform. There is one .dart file for dart, one .m file for swift/objc (plus header), one .java file for java/kotlin. I plan on sticking to that. I've also tried to make the generated code readable. We'd like to have docstrings eventually in the generated code as well.

Thanks again, hopefully my answers get you moving with the issues you are facing today. If you discover something that is missing in the documentation please consider contributing back via PR.

[bsutton]

Thanks for the prompt response.

The video player left me somewhat confused. It doesn't explicitly mentioned that its a federated model and then the IOS code and Android code are both in the main project which left me wondering what was going on.

[bsutton]

I think it is important that the pigeon documentation talks directly to its role in a federated model.

[TytaniumDev]

To add on to this, it would be awesome to have an example of iOS/Android code using the @FlutterApi generated code. I haven't been able to find an example anywhere, and video_player only uses @HostApi

[gaaclarke]

@Tywholland You can check out this example project that uses FlutterApi in the meantime: https://github.com/gaaclarke/GiantsA2A/blob/dc504e4acb8a5f08b53341ad9e9a7afc5cbf97ad/giants/pigeons/messages.dart#L35

[glassmonkey]

Hi.
I made a simple sample app to get the communication status (e.g. wifi, mobile, lost) from native with FlutterApi.

Here's a link

https://github.com/glassmonkey/flutter_wifi

[stuartmorgan]

I think it is important that the pigeon documentation talks directly to its role in a federated model.

In particular, we should document (based on experience with video_player) that Pigeon should not be used in the interface package, only as an internal detail of per-package method channels, to avoid any Pigeon update being a potentially breaking change to the platform interface.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.