[pigeon] Add usage docs to generated Dart event channel methods

[theprantadutta]

The generated event-channel method creates a new EventChannel each time it is called, but nothing in the generated code documented that — making it easy to call repeatedly for the same instance, or to assume the returned stream is single-subscription. This implements the "definitely" part of the linked issue:

Definitely add docs to the generated code, indicated both that it shouldn't be called multiple times for the same instance, and that the returned stream is a broadcast stream.

Each generated event-channel method now gets a usage doc comment:

/// Returns a broadcast [Stream] of events from the `streamEvents` event channel.
///
/// Each call to this method creates a new [EventChannel], so it should
/// not be called multiple times for the same `instanceName`. To deliver
/// events to multiple listeners, call this method once and listen to the
/// returned broadcast stream multiple times instead.

While there, this also emits the user's own documentation comments on event channel methods — previously only the API-level comments were emitted and per-method comments were silently dropped. The two are combined via the existing generatorComments mechanism in addDocumentationComments, which already handles user-comment/generator-comment separation.

The wrapper-object and renaming ideas from the issue are intentionally not addressed here, per the discussion — those are design decisions; this PR is scoped to the documentation gap.

Checked-in generated files containing event channels (example/app and shared_test_plugin_code) are regenerated. The new generator test verifies both the user comments and the usage docs are emitted directly above the generated method, and fails without the generator change.

Fixes flutter/flutter#177776

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under.
• All existing and new tests are passing.

Note: the multi-language auto-formatter step of tool/generate.dart could not run fully on this machine (missing clang-format and related binaries); only Dart outputs changed, and those were formatted with dart format. If CI's format check flags anything, I'll address it.

[gemini-code-assist]

Code Review

This pull request updates the Dart generator in Pigeon to emit usage documentation and user-defined documentation comments on generated event channel methods. It also includes corresponding updates to generated files, tests verifying the new documentation generation, and a version bump to 27.1.1. There are no review comments, so I have no feedback to provide.

[stuartmorgan-g]

LGTM