Document channel message value conversions (#9635)

packages/flutter/lib/src/services/message_codec.dart

@@ -21,12 +21,12 @@ import 'platform_channel.dart';
 abstract class MessageCodec<T> {
   /// Encodes the specified [message] in binary.
   ///
-  /// Returns `null` if the message is `null`.
+  /// Returns null if the message is null.
   ByteData encodeMessage(T message);
 
   /// Decodes the specified [message] from binary.
   ///
-  /// Returns `null` if the message is `null`.
+  /// Returns null if the message is null.
   T decodeMessage(ByteData message);
 }
 
@@ -155,10 +155,10 @@ class PlatformException implements Exception {
   /// An error code.
   final String code;
 
-  /// A human-readable error message, possibly `null`.
+  /// A human-readable error message, possibly null.
   final String message;
 
-  /// Error details, possibly `null`.
+  /// Error details, possibly null.
   final dynamic details;
 
   @override
@@ -174,13 +174,13 @@ class PlatformException implements Exception {
 ///   with a [MissingPluginException], if no plugin handler for the method call
 ///   was found.
 /// * [OptionalMethodChannel.invokeMethod], which completes the returned future
-///   with `null`, if no plugin handler for the method call was found.
+///   with null, if no plugin handler for the method call was found.
 class MissingPluginException implements Exception {
   /// Creates a [MissingPluginException] with an optional human-readable
   /// error message.
   MissingPluginException([this.message]);
 
-  /// A human-readable error message, possibly `null`.
+  /// A human-readable error message, possibly null.
   final String message;
 
   @override

packages/flutter/lib/src/services/message_codecs.dart

@@ -10,6 +10,9 @@ import 'package:flutter/foundation.dart' show ReadBuffer, WriteBuffer, required;
 import 'message_codec.dart';
 
 /// [MessageCodec] with unencoded binary messages represented using [ByteData].
+///
+/// On Android, messages will be represented using `java.nio.ByteBuffer`.
+/// On iOS, messages will be represented using `NSData`.
 class BinaryCodec implements MessageCodec<ByteData> {
   /// Creates a [MessageCodec] with unencoded binary messages represented using
   /// [ByteData].
@@ -23,6 +26,9 @@ class BinaryCodec implements MessageCodec<ByteData> {
 }
 
 /// [MessageCodec] with UTF-8 encoded String messages.
+///
+/// On Android, messages will be represented using `java.util.String`.
+/// On iOS, messages will be represented using `NSString`.
 class StringCodec implements MessageCodec<String> {
   /// Creates a [MessageCodec] with UTF-8 encoded String messages.
   const StringCodec();
@@ -47,12 +53,20 @@ class StringCodec implements MessageCodec<String> {
 ///
 /// Supported messages are acyclic values of these forms:
 ///
-/// * `null`
+/// * null
 /// * [bool]s
 /// * [num]s
 /// * [String]s
 /// * [List]s of supported values
 /// * [Map]s from strings to supported values
+///
+/// On Android, messages are decoded using the `org.json` library.
+/// On iOS, messages are decoded using the `NSJSONSerialization` library.
+/// In both cases, the use of top-level simple messages (null, [bool], [num],
+/// and [String]) is supported (by the Flutter SDK). The decoded value will be
+/// null/nil for null, and identical to what would result from decoding a
+/// singleton JSON array with a Boolean, number, or string value, and then
+/// extracting its single element.
 class JSONMessageCodec implements MessageCodec<dynamic> {
   // The codec serializes messages as defined by the JSON codec of the
   // dart:convert package. The format used must match the Android and
@@ -156,13 +170,45 @@ class JSONMethodCodec implements MethodCodec {
 ///
 /// Supported messages are acyclic values of these forms:
 ///
-/// * `null`
+/// * null
 /// * [bool]s
 /// * [num]s
 /// * [String]s
 /// * [Uint8List]s, [Int32List]s, [Int64List]s, [Float64List]s
 /// * [List]s of supported values
 /// * [Map]s from supported values to supported values
+///
+/// On Android, messages are represented as follows:
+///
+/// * null: null
+/// * [bool]: `java.lang.Boolean`
+/// * [int]: `java.lang.Integer` for values that are representable using 32-bit
+///   two's complement; otherwise, `java.lang.Long` for values that are
+///   representable using 64-bit two's complement; otherwise,
+///   `java.math.BigInteger`.
+/// * [double]: `java.lang.Double`
+/// * [String]: `java.lang.String`
+/// * [Uint8List]: `byte[]`
+/// * [Int32List]: `int[]`
+/// * [Int64List]: `long[]`
+/// * [Float64List]: `double[]`
+/// * [List]: `java.util.ArrayList`
+/// * [Map]: `java.util.HashMap`
+///
+/// On iOS, messages are represented as follows:
+///
+/// * null: nil
+/// * [bool]: `NSNumber numberWithBool:`
+/// * [int]: `NSNumber numberWithInt:` for values that are representable using
+///   32-bit two's complement; otherwise, `NSNumber numberWithLong:` for values
+///   that are representable using 64-bit two's complement; otherwise,
+///   `FlutterStandardBigInteger`.
+/// * [double]: `NSNumber numberWithDouble:`
+/// * [String]: `NSString`
+/// * [Uint8List], [Int32List], [Int64List], [Float64List]:
+///   `FlutterStandardTypedData`
+/// * [List]: `NSArray`
+/// * [Map]: `NSDictionary`
 class StandardMessageCodec implements MessageCodec<dynamic> {
   // The codec serializes messages as outlined below. This format must
   // match the Android and iOS counterparts.

packages/flutter/lib/src/services/platform_channel.dart

@@ -21,7 +21,7 @@ import 'platform_messages.dart';
 /// platform side. The Dart type of messages sent and received is [T],
 /// but only the values supported by the specified [MessageCodec] can be used.
 /// The use of unsupported values should be considered programming errors, and
-/// will result in exceptions being thrown. The `null` message is supported
+/// will result in exceptions being thrown. The null message is supported
 /// for all codecs.
 ///
 /// The logical identity of the channel is given by its name. Identically named
@@ -31,32 +31,32 @@ import 'platform_messages.dart';
 class BasicMessageChannel<T> {
   /// Creates a [BasicMessageChannel] with the specified [name] and [codec].
   ///
-  /// Neither [name] nor [codec] may be `null`.
+  /// Neither [name] nor [codec] may be null.
   const BasicMessageChannel(this.name, this.codec);
 
-  /// The logical channel on which communication happens, not `null`.
+  /// The logical channel on which communication happens, not null.
   final String name;
 
-  /// The message codec used by this channel, not `null`.
+  /// The message codec used by this channel, not null.
   final MessageCodec<T> codec;
 
   /// Sends the specified [message] to the platform plugins on this channel.
   ///
   /// Returns a [Future] which completes to the received response, which may
-  /// be `null`.
+  /// be null.
   Future<T> send(T message) async {
     return codec.decodeMessage(await BinaryMessages.send(name, codec.encodeMessage(message)));
   }
 
   /// Sets a callback for receiving messages from the platform plugins on this
-  /// channel. Messages may be `null`.
+  /// channel. Messages may be null.
   ///
   /// The given callback will replace the currently registered callback for this
-  /// channel, if any. To remove the handler, pass `null` as the `handler`
+  /// channel, if any. To remove the handler, pass null as the `handler`
   /// argument.
   ///
   /// The handler's return value is sent back to the platform plugins as a
-  /// message reply. It may be `null`.
+  /// message reply. It may be null.
   void setMessageHandler(Future<T> handler(T message)) {
     if (handler == null) {
       BinaryMessages.setMessageHandler(name, null);
@@ -68,13 +68,13 @@ class BasicMessageChannel<T> {
   }
 
   /// Sets a mock callback for intercepting messages sent on this channel.
-  /// Messages may be `null`.
+  /// Messages may be null.
   ///
   /// The given callback will replace the currently registered mock callback for
-  /// this channel, if any. To remove the mock handler, pass `null` as the
+  /// this channel, if any. To remove the mock handler, pass null as the
   /// `handler` argument.
   ///
-  /// The handler's return value is used as a message reply. It may be `null`.
+  /// The handler's return value is used as a message reply. It may be null.
   ///
   /// This is intended for testing. Messages intercepted in this manner are not
   /// sent to platform plugins.
@@ -99,7 +99,7 @@ class BasicMessageChannel<T> {
 /// platform side. The Dart type of arguments and results is `dynamic`,
 /// but only values supported by the specified [MethodCodec] can be used.
 /// The use of unsupported values should be considered programming errors, and
-/// will result in exceptions being thrown. The `null` value is supported
+/// will result in exceptions being thrown. The null value is supported
 /// for all codecs.
 ///
 /// The logical identity of the channel is given by its name. Identically named
@@ -112,20 +112,20 @@ class MethodChannel {
   /// The [codec] used will be [StandardMethodCodec], unless otherwise
   /// specified.
   ///
-  /// Neither [name] nor [codec] may be `null`.
+  /// Neither [name] nor [codec] may be null.
   const MethodChannel(this.name, [this.codec = const StandardMethodCodec()]);
 
-  /// The logical channel on which communication happens, not `null`.
+  /// The logical channel on which communication happens, not null.
   final String name;
 
-  /// The message codec used by this channel, not `null`.
+  /// The message codec used by this channel, not null.
   final MethodCodec codec;
 
   /// Invokes a [method] on this channel with the specified [arguments].
   ///
   /// Returns a [Future] which completes to one of the following:
   ///
-  /// * a result (possibly `null`), on successful invocation;
+  /// * a result (possibly null), on successful invocation;
   /// * a [PlatformException], if the invocation failed in the platform plugin;
   /// * a [MissingPluginException], if the method has not been implemented by a
   ///   platform plugin.
@@ -143,7 +143,7 @@ class MethodChannel {
   /// Sets a callback for receiving method calls on this channel.
   ///
   /// The given callback will replace the currently registered callback for this
-  /// channel, if any. To remove the handler, pass `null` as the
+  /// channel, if any. To remove the handler, pass null as the
   /// `handler` argument.
   ///
   /// If the future returned by the handler completes with a result, that value
@@ -164,7 +164,7 @@ class MethodChannel {
   /// Sets a mock callback for intercepting method invocations on this channel.
   ///
   /// The given callback will replace the currently registered mock callback for
-  /// this channel, if any. To remove the mock handler, pass `null` as the
+  /// this channel, if any. To remove the mock handler, pass null as the
   /// `handler` argument.
   ///
   /// Later calls to [invokeMethod] will result in a successful result,
@@ -238,20 +238,20 @@ class EventChannel {
   /// The [codec] used will be [StandardMethodCodec], unless otherwise
   /// specified.
   ///
-  /// Neither [name] nor [codec] may be `null`.
+  /// Neither [name] nor [codec] may be null.
   const EventChannel(this.name, [this.codec = const StandardMethodCodec()]);
 
-  /// The logical channel on which communication happens, not `null`.
+  /// The logical channel on which communication happens, not null.
   final String name;
 
-  /// The message codec used by this channel, not `null`.
+  /// The message codec used by this channel, not null.
   final MethodCodec codec;
 
   /// Sets up a broadcast stream for receiving events on this channel.
   ///
   /// Returns a broadcast [Stream] which emits events to listeners as follows:
   ///
-  /// * a decoded data event (possibly `null`) for each successful event
+  /// * a decoded data event (possibly null) for each successful event
   /// received from the platform plugin;
   /// * an error event containing a [PlatformException] for each error event
   /// received from the platform plugin;

packages/flutter/lib/src/services/platform_messages.dart

@@ -92,7 +92,7 @@ class BinaryMessages {
   /// given channel, without decoding them.
   ///
   /// The given callback will replace the currently registered callback for that
-  /// channel, if any. To remove the handler, pass `null` as the `handler`
+  /// channel, if any. To remove the handler, pass null as the `handler`
   /// argument.
   ///
   /// The handler's return value, if non-null, is sent as a response, unencoded.
@@ -107,7 +107,7 @@ class BinaryMessages {
   /// this class, on the given channel, without decoding them.
   ///
   /// The given callback will replace the currently registered mock callback for
-  /// that channel, if any. To remove the mock handler, pass `null` as the
+  /// that channel, if any. To remove the mock handler, pass null as the
   /// `handler` argument.
   ///
   /// The handler's return value, if non-null, is used as a response, unencoded.