[dartdoc] Updating dart reference docs
diff --git a/sdk/dart/package-fidl_fidl/decodeMessage.md b/sdk/dart/package-fidl_fidl/decodeMessage.md
index 3c492f0..dedcd8a 100644
--- a/sdk/dart/package-fidl_fidl/decodeMessage.md
+++ b/sdk/dart/package-fidl_fidl/decodeMessage.md
@@ -7,9 +7,7 @@
T decodeMessage
<T>([Message](../package-fidl_fidl/Message-class.md) message, int inlineSize, [MemberType](../package-fidl_fidl/MemberType-class.md) typ)
-<p>Decodes a single FIDL message. Most messages can be decoded using this
-entry point. Such a messages generally take the form of header bytes
-followed immediately by the encoded message bytes.</p>
+<p>Decodes a FIDL message that contains a single parameter.</p>
## Implementation
diff --git a/sdk/dart/package-fidl_fidl/decodeMessageWithCallback.md b/sdk/dart/package-fidl_fidl/decodeMessageWithCallback.md
index 5971867..ece51c5 100644
--- a/sdk/dart/package-fidl_fidl/decodeMessageWithCallback.md
+++ b/sdk/dart/package-fidl_fidl/decodeMessageWithCallback.md
@@ -7,10 +7,16 @@
A decodeMessageWithCallback
<A>([Message](../package-fidl_fidl/Message-class.md) message, int inlineSize, A f([Decoder](../package-fidl_fidl/Decoder-class.md) decoder))
-<p>Decodes a FIDL message with multiple parameters. Such messages generally
-take the form of header bytes followed by the encoded bytes of each
-parameter in turn. The generated bindings should then wrap the resulting
-parameter types into a single "Async___Class" inside the callback function.</p>
+<p>Decodes a FIDL message with multiple parameters. The callback parameter
+provides a decoder that is initialized on the provided Message, which
+callers can use to decode specific types. The return result of the callback
+(e.g. the decoded parameters, wrapped in a containing class/struct) is
+returned as the result of the function. This functionality (decoding
+multiple parameters) is implemented using a callback because returning a
+list would be insufficient: the list would be of type List<fidltype>,
+whereas we want to retain concrete types of each decoded parameter. The
+only way to accomplish this in Dart is to pass in a function that collects
+these multiple values into a bespoke, properly typed class.</fidltype></p>
## Implementation
diff --git a/sdk/dart/package-fidl_fidl/encodeMessage.md b/sdk/dart/package-fidl_fidl/encodeMessage.md
index afc2f9a..fad40de 100644
--- a/sdk/dart/package-fidl_fidl/encodeMessage.md
+++ b/sdk/dart/package-fidl_fidl/encodeMessage.md
@@ -7,6 +7,7 @@
void encodeMessage
<T>([Encoder](../package-fidl_fidl/Encoder-class.md) encoder, int inlineSize, [MemberType](../package-fidl_fidl/MemberType-class.md) typ, T value)
+<p>Encodes a FIDL message that contains a single parameter.</p>
## Implementation
diff --git a/sdk/dart/package-fidl_fidl/encodeMessageWithCallback.md b/sdk/dart/package-fidl_fidl/encodeMessageWithCallback.md
index 40a7f58..fe25a75 100644
--- a/sdk/dart/package-fidl_fidl/encodeMessageWithCallback.md
+++ b/sdk/dart/package-fidl_fidl/encodeMessageWithCallback.md
@@ -7,6 +7,12 @@
void encodeMessageWithCallback
([Encoder](../package-fidl_fidl/Encoder-class.md) encoder, int inlineSize, dynamic f())
+<p>Encodes a FIDL message with multiple parameters. The callback parameter
+provides a decoder that is initialized on the provided Message, which
+callers can use to decode specific types. This functionality (encoding
+multiple parameters) is implemented using a callback because each call to
+MemberType.encode() must pass in a concrete type, rather than an element
+popped from a List<fidltype>.</fidltype></p>
## Implementation
diff --git a/sdk/dart/package-fidl_fidl/package-fidl_fidl-library.md b/sdk/dart/package-fidl_fidl/package-fidl_fidl-library.md
index 2cb9784..ad180b8 100644
--- a/sdk/dart/package-fidl_fidl/package-fidl_fidl-library.md
+++ b/sdk/dart/package-fidl_fidl/package-fidl_fidl-library.md
@@ -336,27 +336,36 @@
##### [decodeMessage](../package-fidl_fidl/decodeMessage.md)<T>([Message](../package-fidl_fidl/Message-class.md) message, int inlineSize, [MemberType](../package-fidl_fidl/MemberType-class.md) typ) T
-Decodes a single FIDL message. Most messages can be decoded using this
-entry point. Such a messages generally take the form of header bytes
-followed immediately by the encoded message bytes.
+Decodes a FIDL message that contains a single parameter.
##### [decodeMessageWithCallback](../package-fidl_fidl/decodeMessageWithCallback.md)<A>([Message](../package-fidl_fidl/Message-class.md) message, int inlineSize, A f([Decoder](../package-fidl_fidl/Decoder-class.md) decoder)) A
-Decodes a FIDL message with multiple parameters. Such messages generally
-take the form of header bytes followed by the encoded bytes of each
-parameter in turn. The generated bindings should then wrap the resulting
-parameter types into a single "Async___Class" inside the callback function.
+Decodes a FIDL message with multiple parameters. The callback parameter
+provides a decoder that is initialized on the provided Message, which
+callers can use to decode specific types. The return result of the callback
+(e.g. the decoded parameters, wrapped in a containing class/struct) is
+returned as the result of the function. This functionality (decoding
+multiple parameters) is implemented using a callback because returning a
+list would be insufficient: the list would be of type List<fidltype>,
+whereas we want to retain concrete types of each decoded parameter. The
+only way to accomplish this in Dart is to pass in a function that collects
+these multiple values into a bespoke, properly typed class.</fidltype>
##### [encodeMessage](../package-fidl_fidl/encodeMessage.md)<T>([Encoder](../package-fidl_fidl/Encoder-class.md) encoder, int inlineSize, [MemberType](../package-fidl_fidl/MemberType-class.md) typ, T value) void
-
+Encodes a FIDL message that contains a single parameter.
##### [encodeMessageWithCallback](../package-fidl_fidl/encodeMessageWithCallback.md)([Encoder](../package-fidl_fidl/Encoder-class.md) encoder, int inlineSize, dynamic f()) void
-
+Encodes a FIDL message with multiple parameters. The callback parameter
+provides a decoder that is initialized on the provided Message, which
+callers can use to decode specific types. This functionality (encoding
+multiple parameters) is implemented using a callback because each call to
+MemberType.encode() must pass in a concrete type, rather than an element
+popped from a List<fidltype>.</fidltype>
