Document channel message value conversions (#3633)

shell/platform/android/io/flutter/plugin/common/BinaryCodec.java

@@ -7,7 +7,14 @@ package io.flutter.plugin.common;
 import java.nio.ByteBuffer;
 
 /**
- * A {@link MessageCodec} using unencoded binary messages, represented as {@link ByteBuffer}s.
+ * A {@link MessageCodec} using unencoded binary messages, represented as
+ * {@link ByteBuffer}s.
+ *
+ * <p>This codec is guaranteed to be compatible with the corresponding
+ * <a href="https://docs.flutter.io/flutter/services/BinaryCodec-class.html">BinaryCodec</a>
+ * on the Dart side. These parts of the Flutter SDK are evolved synchronously.</p>
+ *
+ * <p>On the Dart side, messages are represented using {@code ByteData}.</p>
  */
 public final class BinaryCodec implements MessageCodec<ByteBuffer> {
     // This codec must match the Dart codec of the same name in package flutter/services.

shell/platform/android/io/flutter/plugin/common/JSONMessageCodec.java

@@ -12,7 +12,15 @@ import org.json.JSONTokener;
 /**
  * A {@link MessageCodec} using UTF-8 encoded JSON messages.
  *
- * Supports the same Java values as {@link JSONObject#wrap(Object)}.
+ * <p>This codec is guaranteed to be compatible with the corresponding
+ * <a href="https://docs.flutter.io/flutter/services/JSONMessageCodec-class.html">JSONMessageCodec</a>
+ * on the Dart side. These parts of the Flutter SDK are evolved synchronously.</p>
+ *
+ * <p>Supports the same Java values as {@link JSONObject#wrap(Object)}.</p>
+ *
+ * <p>On the Dart side, JSON messages are handled by the JSON facilities of the
+ * <a href="https://api.dartlang.org/stable/dart-convert/JSON-constant.html">dart:convert</a>
+ * package.</p>
  */
 public final class JSONMessageCodec implements MessageCodec<Object> {
     // This codec must match the Dart codec of the same name in package flutter/services.

shell/platform/android/io/flutter/plugin/common/JSONMethodCodec.java

@@ -7,8 +7,13 @@ import org.json.JSONObject;
 
 /**
  * A {@link MethodCodec} using UTF-8 encoded JSON method calls and result envelopes.
- * Values supported as methods arguments and result payloads are those supported by
- * {@link JSONMessageCodec}.
+ *
+ * <p>This codec is guaranteed to be compatible with the corresponding
+ * <a href="https://docs.flutter.io/flutter/services/JSONMethodCodec-class.html">JSONMethodCodec</a>
+ * on the Dart side. These parts of the Flutter SDK are evolved synchronously.</p>
+ *
+ * <p>Values supported as methods arguments and result payloads are those supported by
+ * {@link JSONMessageCodec}.</p>
  */
 public final class JSONMethodCodec implements MethodCodec {
     // This codec must match the Dart codec of the same name in package flutter/services.

shell/platform/android/io/flutter/plugin/common/StandardMessageCodec.java

@@ -18,11 +18,11 @@ import java.util.Map.Entry;
 /**
  * MessageCodec using the Flutter standard binary encoding.
  *
- * The standard encoding is guaranteed to be compatible with the corresponding standard codec
- * for PlatformMessageChannels on the Flutter side. These parts of the Flutter SDK are evolved
- * synchronously.
+ * <p>This codec is guaranteed to be compatible with the corresponding
+ * <a href="https://docs.flutter.io/flutter/services/StandardMessageCodec-class.html">StandardMessageCodec</a>
+ * on the Dart side. These parts of the Flutter SDK are evolved synchronously.</p>
  *
- * Supported messages are acyclic values of these forms:
+ * <p>Supported messages are acyclic values of these forms:</p>
  *
  * <ul>
  *     <li>null</li>
@@ -34,9 +34,24 @@ import java.util.Map.Entry;
  *     <li>Lists of supported values</li>
  *     <li>Maps with supported keys and values</li>
  * </ul>
+ *
+ * <p>On the Dart side, these values are represented as follows:</p>
+ *
+ * <ul>
+ *     <li>null: null</li>
+ *     <li>Boolean: bool</li>
+ *     <li>Byte, Short, Integer, Long, BigInteger: int</li>
+ *     <li>Float, Double: double</li>
+ *     <li>String: String</li>
+ *     <li>byte[]: Uint8List</li>
+ *     <li>int[]: Int32List</li>
+ *     <li>long[]: Int64List</li>
+ *     <li>double[]: Float64List</li>
+ *     <li>List: List</li>
+ *     <li>Map: Map</li>
+ * </ul>
  */
 public final class StandardMessageCodec implements MessageCodec<Object> {
-    // This codec must match the Dart codec of the same name in package flutter/services.
     public static final StandardMessageCodec INSTANCE = new StandardMessageCodec();
 
     private StandardMessageCodec() {

shell/platform/android/io/flutter/plugin/common/StandardMethodCodec.java

@@ -11,15 +11,14 @@ import java.nio.ByteOrder;
 /**
  * A {@link MethodCodec} using the Flutter standard binary encoding.
  *
- * The standard codec is guaranteed to be compatible with the corresponding standard codec for
- * PlatformMethodChannels on the Flutter side. These parts of the Flutter SDK are evolved
- * synchronously.
+ * <p>This codec is guaranteed to be compatible with the corresponding
+ * <a href="https://docs.flutter.io/flutter/services/StandardMethodCodec-class.html">StandardMethodCodec</a>
+ * on the Dart side. These parts of the Flutter SDK are evolved synchronously.</p>
  *
- * Values supported as method arguments and result payloads are those supported by
- * {@link StandardMessageCodec}.
+ * <p>Values supported as method arguments and result payloads are those supported by
+ * {@link StandardMessageCodec}.</p>
  */
 public final class StandardMethodCodec implements MethodCodec {
-    // This codec must match the Dart codec of the same name in package flutter/services.
     public static final StandardMethodCodec INSTANCE = new StandardMethodCodec();
 
     private StandardMethodCodec() {

shell/platform/android/io/flutter/plugin/common/StringCodec.java

@@ -9,9 +9,12 @@ import java.nio.charset.Charset;
 
 /**
  * A {@link MessageCodec} using UTF-8 encoded String messages.
+ *
+ * <p>This codec is guaranteed to be compatible with the corresponding
+ * <a href="https://docs.flutter.io/flutter/services/StringCodec-class.html">StringCodec</a>
+ * on the Dart side. These parts of the Flutter SDK are evolved synchronously.</p>
  */
 public final class StringCodec implements MessageCodec<String> {
-    // This codec must match the Dart codec of the same name in package flutter/services.
     private static final Charset UTF8 = Charset.forName("UTF8");
     public static final StringCodec INSTANCE = new StringCodec();
 

shell/platform/darwin/ios/framework/Headers/FlutterCodecs.h

@@ -40,6 +40,12 @@ FLUTTER_EXPORT
 /**
  A `FlutterMessageCodec` using unencoded binary messages, represented as
  `NSData` instances.
+
+ This codec is guaranteed to be compatible with the corresponding
+ [BinaryCodec](https://docs.flutter.io/flutter/services/BinaryCodec-class.html)
+ on the Dart side. These parts of the Flutter SDK are evolved synchronously.
+
+ On the Dart side, messages are represented using `ByteData`.
  */
 FLUTTER_EXPORT
 @interface FlutterBinaryCodec : NSObject<FlutterMessageCodec>
@@ -47,6 +53,10 @@ FLUTTER_EXPORT
 
 /**
  A `FlutterMessageCodec` using UTF-8 encoded `NSString` messages.
+
+ This codec is guaranteed to be compatible with the corresponding
+ [StringCodec](https://docs.flutter.io/flutter/services/StringCodec-class.html)
+ on the Dart side. These parts of the Flutter SDK are evolved synchronously.
  */
 FLUTTER_EXPORT
 @interface FlutterStringCodec : NSObject<FlutterMessageCodec>
@@ -55,7 +65,16 @@ FLUTTER_EXPORT
 /**
  A `FlutterMessageCodec` using UTF-8 encoded JSON messages.
 
- Supports the same values as `NSJSONSerialization`.
+ This codec is guaranteed to be compatible with the corresponding
+ [JSONMessageCodec](https://docs.flutter.io/flutter/services/JSONMessageCodec-class.html)
+ on the Dart side. These parts of the Flutter SDK are evolved synchronously.
+
+ Supports values accepted by `NSJSONSerialization` plus top-level
+ `nil`, `NSNumber`, and `NSString`.
+
+ On the Dart side, JSON messages are handled by the JSON facilities of the
+ [`dart:convert`](https://api.dartlang.org/stable/dart-convert/JSON-constant.html)
+ package.
  */
 FLUTTER_EXPORT
 @interface FlutterJSONMessageCodec : NSObject<FlutterMessageCodec>
@@ -64,19 +83,29 @@ FLUTTER_EXPORT
 /**
  A `FlutterMessageCodec` using the Flutter standard binary encoding.
 
- The standard encoding is guaranteed to be compatible with the corresponding
- standard codec for PlatformMessageChannels on the Flutter side. These parts
- of the Flutter SDK are evolved synchronously.
+ This codec is guaranteed to be compatible with the corresponding
+ [StandardMessageCodec](https://docs.flutter.io/flutter/services/StandardMessageCodec-class.html)
+ on the Dart side. These parts of the Flutter SDK are evolved synchronously.
 
  Supported messages are acyclic values of these forms:
 
  - `nil` or `NSNull`
  - `NSNumber` (including their representation of Boolean values)
  - `FlutterStandardBigInteger`
- - `FlutterStandardTypedData`
  - `NSString`
+ - `FlutterStandardTypedData`
  - `NSArray` of supported values
  - `NSDictionary` with supported keys and values
+
+ On the Dart side, these values are represented as follows:
+
+ - `nil` or `NSNull`: `null`
+ - `NSNumber`: `bool`, `int`, or `double`, depending on the contained value.
+ - `FlutterStandardBigInteger`: `int`
+ - `NSString`: `String`
+ - `FlutterStandardTypedData`: `Uint8List`, `Int32List`, `Int64List`, or `Float64List`
+ - `NSArray`: `List`
+ - `NSDictionary`: `Map`
  */
 FLUTTER_EXPORT
 @interface FlutterStandardMessageCodec : NSObject<FlutterMessageCodec>
@@ -308,7 +337,13 @@ FLUTTER_EXPORT
 
 /**
  A `FlutterMethodCodec` using UTF-8 encoded JSON method calls and result
- envelopes. Values supported as methods arguments and result payloads are
+ envelopes.
+
+ This codec is guaranteed to be compatible with the corresponding
+ [JSONMethodCodec](https://docs.flutter.io/flutter/services/JSONMethodCodec-class.html)
+ on the Dart side. These parts of the Flutter SDK are evolved synchronously.
+
+ Values supported as methods arguments and result payloads are
  those supported as top-level or leaf values by `FlutterJSONMessageCodec`.
  */
 FLUTTER_EXPORT
@@ -318,9 +353,9 @@ FLUTTER_EXPORT
 /**
  A `FlutterMethodCodec` using the Flutter standard binary encoding.
 
- The standard codec is guaranteed to be compatible with the corresponding
- standard codec for PlatformMethodChannels on the Flutter side. These parts of
- the Flutter SDK are evolved synchronously.
+ This codec is guaranteed to be compatible with the corresponding
+ [StandardMethodCodec](https://docs.flutter.io/flutter/services/StandardMethodCodec-class.html)
+ on the Dart side. These parts of the Flutter SDK are evolved synchronously.
 
  Values supported as method arguments and result payloads are those supported by
  `FlutterStandardMessageCodec`.