[pigeon] Add usage docs to generated Dart event channel methods (#11894)

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:

```dart
/// 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 https://github.com/flutter/flutter/issues/177776

## Pre-Review Checklist

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.