Repository navigation
[pigeon] improve documentation #66511
Description
Activity
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_playeris the definitive example: https://github.com/flutter/plugins/tree/master/packages/video_playerAs 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-team-archive/plugins@c65bdd0#diff-1119d814fb92c6c6cff89707b50874ecI 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
HostApiandFlutterApiand 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.
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.
I think it is important that the pigeon documentation talks directly to its role in a federated model.
To add on to this, it would be awesome to have an example of iOS/Android code using the
@FlutterApigenerated code. I haven't been able to find an example anywhere, andvideo_playeronly uses@HostApiReacted by gaaclarke, Oren Agiv and Dante@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
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
Reacted by gianlucaparadise, vitorreda and Dhruv NakumI 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.- added a commit that references this issue
on Apr 20, 2023 - added a commit that references this issue
on Jun 30, 2023 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 -vand a minimal reproduction of the issue.- locked as resolved and limited conversation to collaborators
on Jul 14, 2023 - added a commit that references this issue
on Jun 10, 2026 - added a commit that references this issue
on Jun 19, 2026
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.