From 784e5d7ded9771409b0dbb9079880dab35fc5d26 Mon Sep 17 00:00:00 2001
From: Robert Ancell <robert.ancell@canonical.com>
Date: Wed, 20 May 2020 09:14:28 +1200
Subject: [PATCH] Update comments for grammar and content to required style
 (#18491)

---
 shell/platform/linux/fl_binary_codec_test.cc  |   6 +-
 .../linux/fl_binary_messenger_private.h       |   3 +-
 shell/platform/linux/fl_engine_private.h      |  62 +++---
 shell/platform/linux/fl_renderer.h            |  31 +--
 shell/platform/linux/fl_renderer_x11.h        |  12 +-
 .../linux/fl_standard_message_codec_private.h |  41 ++--
 shell/platform/linux/fl_string_codec_test.cc  |   6 +-
 shell/platform/linux/fl_view.cc               |  12 ++
 .../flutter_linux/fl_basic_message_channel.h  |  93 ++++++---
 .../public/flutter_linux/fl_binary_codec.h    |   7 +-
 .../flutter_linux/fl_binary_messenger.h       |  52 ++---
 .../public/flutter_linux/fl_dart_project.h    |  24 +--
 .../linux/public/flutter_linux/fl_engine.h    |   6 +-
 .../flutter_linux/fl_json_message_codec.h     |  33 +--
 .../public/flutter_linux/fl_message_codec.h   |  44 ++--
 .../flutter_linux/fl_standard_message_codec.h |   8 +-
 .../public/flutter_linux/fl_string_codec.h    |   7 +-
 .../linux/public/flutter_linux/fl_value.h     | 196 ++++++++++++------
 .../linux/public/flutter_linux/fl_view.h      |  18 +-
 19 files changed, 405 insertions(+), 256 deletions(-)

diff --git a/shell/platform/linux/fl_binary_codec_test.cc b/shell/platform/linux/fl_binary_codec_test.cc
index 5405e8a0d..76f8b2491 100644
--- a/shell/platform/linux/fl_binary_codec_test.cc
+++ b/shell/platform/linux/fl_binary_codec_test.cc
@@ -6,7 +6,7 @@
 #include "flutter/shell/platform/linux/testing/fl_test.h"
 #include "gtest/gtest.h"
 
-// Encode a message using a FlBinaryCodec. Return a hex string with the encoded
+// Encodes a message using a FlBinaryCodec. Return a hex string with the encoded
 // binary output.
 static gchar* encode_message(FlValue* value) {
   g_autoptr(FlBinaryCodec) codec = fl_binary_codec_new();
@@ -19,7 +19,7 @@ static gchar* encode_message(FlValue* value) {
   return bytes_to_hex_string(message);
 }
 
-// Encode a message using a FlBinaryCodec. Expect the given error.
+// Encodes a message using a FlBinaryCodec. Expect the given error.
 static void encode_message_error(FlValue* value, GQuark domain, int code) {
   g_autoptr(FlBinaryCodec) codec = fl_binary_codec_new();
   g_autoptr(GError) error = nullptr;
@@ -29,7 +29,7 @@ static void encode_message_error(FlValue* value, GQuark domain, int code) {
   EXPECT_TRUE(g_error_matches(error, domain, code));
 }
 
-// Decode a message using a FlBinaryCodec. The binary data is given in the form
+// Decodes a message using a FlBinaryCodec. The binary data is given in the form
 // of a hex string.
 static FlValue* decode_message(const char* hex_string) {
   g_autoptr(FlBinaryCodec) codec = fl_binary_codec_new();
diff --git a/shell/platform/linux/fl_binary_messenger_private.h b/shell/platform/linux/fl_binary_messenger_private.h
index 88212c174..ce70c51dc 100644
--- a/shell/platform/linux/fl_binary_messenger_private.h
+++ b/shell/platform/linux/fl_binary_messenger_private.h
@@ -15,7 +15,8 @@ G_BEGIN_DECLS
  * fl_binary_messenger_new:
  * @engine: The #FlEngine to communicate with.
  *
- * Create a new #FlBinaryMessenger.
+ * Creates a new #FlBinaryMessenger. The binary messenger will take control of
+ * the engines platform message handler.
  *
  * Returns: a new #FlBinaryMessenger.
  */
diff --git a/shell/platform/linux/fl_engine_private.h b/shell/platform/linux/fl_engine_private.h
index da91a16c9..1007cfe75 100644
--- a/shell/platform/linux/fl_engine_private.h
+++ b/shell/platform/linux/fl_engine_private.h
@@ -27,11 +27,11 @@ GQuark fl_engine_error_quark(void) G_GNUC_CONST;
 
 /**
  * FlEnginePlatformMessageHandler:
- * @engine: a #FlEngine
+ * @engine: an #FlEngine.
  * @channel: channel message received on.
- * @message: message content received from Dart
- * @response_handle: a handle to respond to the message with
- * @user_data: (closure): data provided when registering this handler
+ * @message: message content received from Dart.
+ * @response_handle: a handle to respond to the message with.
+ * @user_data: (closure): data provided when registering this handler.
  *
  * Function called when platform messages are received.
  *
@@ -46,25 +46,25 @@ typedef gboolean (*FlEnginePlatformMessageHandler)(
 
 /**
  * fl_engine_new:
- * @project: a #FlDartProject
- * @renderer: a #FlRenderer
+ * @project: an #FlDartProject.
+ * @renderer: an #FlRenderer.
  *
- * Creates a new Flutter engine.
+ * Creates new Flutter engine.
  *
- * Returns: a #FlEngine
+ * Returns: a new #FlEngine.
  */
 FlEngine* fl_engine_new(FlDartProject* project, FlRenderer* renderer);
 
 /**
  * fl_engine_set_platform_message_handler:
- * @engine: a #FlEngine
- * @handler: function to call when a platform message is received
- * @user_data: (closure): user data to pass to @handler
+ * @engine: an #FlEngine.
+ * @handler: function to call when a platform message is received.
+ * @user_data: (closure): user data to pass to @handler.
  *
- * Register a handler to handle platform messages. Call
- * fl_engine_send_platform_message_response() when this message should be
- * responded to. Ownership of #FlutterPlatformMessageResponseHandle is
- * transferred to the caller, and the call must be responded to to avoid
+ * Registers the function called when a platform message is reveived. Call
+ * fl_engine_send_platform_message_response() with the response to this message.
+ * Ownership of #FlutterPlatformMessageResponseHandle is
+ * transferred to the caller, and the message must be responded to to avoid
  * memory leaks.
  */
 void fl_engine_set_platform_message_handler(
@@ -74,19 +74,19 @@ void fl_engine_set_platform_message_handler(
 
 /**
  * fl_engine_start:
- * @engine: a #FlEngine
+ * @engine: an #FlEngine.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
  * Starts the Flutter engine.
  *
- * Returns: %TRUE on success
+ * Returns: %TRUE on success.
  */
 gboolean fl_engine_start(FlEngine* engine, GError** error);
 
 /**
  * fl_engine_send_window_metrics_event:
- * @engine: a #FlEngine
+ * @engine: an #FlEngine.
  * @width: width of the window in pixels.
  * @height: height of the window in pixels.
  * @pixel_ratio: scale factor for window.
@@ -100,7 +100,7 @@ void fl_engine_send_window_metrics_event(FlEngine* engine,
 
 /**
  * fl_engine_send_mouse_pointer_event:
- * @engine: a #FlEngine
+ * @engine: an #FlEngine.
  * @phase: mouse phase.
  * @timestamp: time when event occurred in microseconds.
  * @x: x location of mouse cursor.
@@ -118,13 +118,13 @@ void fl_engine_send_mouse_pointer_event(FlEngine* engine,
 
 /**
  * fl_engine_send_platform_message_response:
- * @engine: a #FlEngine
- * @handle: handle that was provided in #FlEnginePlatformMessageHandler
+ * @engine: an #FlEngine.
+ * @handle: handle that was provided in #FlEnginePlatformMessageHandler.
  * @response: (allow-none): response to send or %NULL for an empty response.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
- * Respond to a platform message.
+ * Responds to a platform message.
  *
  * Returns: %TRUE on success.
  */
@@ -136,15 +136,15 @@ gboolean fl_engine_send_platform_message_response(
 
 /**
  * fl_engine_send_platform_message:
- * @engine: a #FlEngine
- * @channel: channel to send to
+ * @engine: an #FlEngine.
+ * @channel: channel to send to.
  * @message: (allow-none): message buffer to send or %NULL for an empty message
- * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL.
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
- * satisfied
- * @user_data: (closure): user data to pass to @callback
+ * satisfied.
+ * @user_data: (closure): user data to pass to @callback.
  *
- * Asynchronously send a platform message.
+ * Asynchronously sends a platform message.
  */
 void fl_engine_send_platform_message(FlEngine* engine,
                                      const gchar* channel,
@@ -155,12 +155,12 @@ void fl_engine_send_platform_message(FlEngine* engine,
 
 /**
  * fl_engine_send_platform_message_finish:
- * @engine: a #FlEngine
- * @result: a #GAsyncResult
+ * @engine: an #FlEngine.
+ * @result: a #GAsyncResult.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
- * Complete request started with fl_engine_send_platform_message().
+ * Completes request started with fl_engine_send_platform_message().
  *
  * Returns: message response on success or %NULL on error.
  */
diff --git a/shell/platform/linux/fl_renderer.h b/shell/platform/linux/fl_renderer.h
index 587e9609a..58063f347 100644
--- a/shell/platform/linux/fl_renderer.h
+++ b/shell/platform/linux/fl_renderer.h
@@ -35,8 +35,11 @@ G_DECLARE_DERIVABLE_TYPE(FlRenderer, fl_renderer, FL, RENDERER, GObject)
 struct _FlRendererClass {
   GObjectClass parent_class;
 
-  // Virtual methods
+  // Virtual method called when Flutter has set up EGL and is ready for the
+  // renderer to start.
   gboolean (*start)(FlRenderer* renderer, GError** error);
+
+  // Virtual method called when flutter needs a surface to render to.
   EGLSurface (*create_surface)(FlRenderer* renderer,
                                EGLDisplay display,
                                EGLConfig config);
@@ -44,68 +47,70 @@ struct _FlRendererClass {
 
 /**
  * fl_renderer_start:
- * @renderer: a #FlRenderer
+ * @renderer: an #FlRenderer.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
+ * Start the renderer. EGL must be set up before this call.
+ *
  * Returns: %TRUE if successfully started.
  */
 gboolean fl_renderer_start(FlRenderer* self, GError** error);
 
 /**
  * fl_renderer_get_proc_address:
- * @renderer: a #FlRenderer
- * @name: a function name
+ * @renderer: an #FlRenderer.
+ * @name: a function name.
  *
  * Gets the rendering API function that matches the given name.
  *
- * Returns: a function pointer
+ * Returns: a function pointer.
  */
 void* fl_renderer_get_proc_address(FlRenderer* renderer, const char* name);
 
 /**
  * fl_renderer_make_current:
- * @renderer: a #FlRenderer
+ * @renderer: an #FlRenderer.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
  * Makes the rendering context current.
  *
- * Returns %TRUE if successful
+ * Returns %TRUE if successful.
  */
 gboolean fl_renderer_make_current(FlRenderer* renderer, GError** error);
 
 /**
  * fl_renderer_clear_current:
- * @renderer: a #FlRenderer
+ * @renderer: an #FlRenderer.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
  * Clears the current rendering context.
  *
- * Returns %TRUE if successful
+ * Returns %TRUE if successful.
  */
 gboolean fl_renderer_clear_current(FlRenderer* renderer, GError** error);
 
 /**
  * fl_renderer_get_fbo:
- * @renderer: a #FlRenderer
+ * @renderer: an #FlRenderer.
  *
  * Gets the frame buffer object to render to.
  *
- * Returns: a frame buffer object index
+ * Returns: a frame buffer object index.
  */
 guint32 fl_renderer_get_fbo(FlRenderer* renderer);
 
 /**
  * fl_renderer_present:
- * @renderer: a #FlRenderer
+ * @renderer: an #FlRenderer.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
  * Presents the current frame.
  *
- * Returns %TRUE if successful
+ * Returns %TRUE if successful.
  */
 gboolean fl_renderer_present(FlRenderer* renderer, GError** error);
 
diff --git a/shell/platform/linux/fl_renderer_x11.h b/shell/platform/linux/fl_renderer_x11.h
index ca3634172..14b19e57f 100644
--- a/shell/platform/linux/fl_renderer_x11.h
+++ b/shell/platform/linux/fl_renderer_x11.h
@@ -20,25 +20,25 @@ G_DECLARE_FINAL_TYPE(FlRendererX11,
 /**
  * FlRendererX11:
  *
- * #FlRendererX11 is an implementation of a #FlRenderer that renders to X11
+ * #FlRendererX11 is an implementation of #FlRenderer that renders to X11
  * windows.
  */
 
 /**
  * fl_renderer_x11_new:
  *
- * Create an object that allows Flutter to render to X11 windows.
+ * Creates an object that allows Flutter to render to X11 windows.
  *
- * Returns: a #FlRendererX11
+ * Returns: a new #FlRendererX11.
  */
 FlRendererX11* fl_renderer_x11_new();
 
 /**
  * fl_renderer_x11_set_xid:
- * @renderer: a #FlRendererX11
- * @xid: The X window being rendered to
+ * @renderer: an #FlRendererX11.
+ * @xid: The X window being rendered to.
  *
- * Set the X11 window that is being rendered to.
+ * Sets the X11 window that is being rendered to.
  */
 void fl_renderer_x11_set_xid(FlRendererX11* renderer, Window xid);
 
diff --git a/shell/platform/linux/fl_standard_message_codec_private.h b/shell/platform/linux/fl_standard_message_codec_private.h
index c14ec9582..82cebef73 100644
--- a/shell/platform/linux/fl_standard_message_codec_private.h
+++ b/shell/platform/linux/fl_standard_message_codec_private.h
@@ -11,9 +11,9 @@ G_BEGIN_DECLS
 
 /**
  * fl_standard_message_codec_write_size:
- * @codec: a #FlStandardMessageCodec
- * @buffer: buffer to write into
- * @size: size value to write
+ * @codec: an #FlStandardMessageCodec.
+ * @buffer: buffer to write into.
+ * @size: size value to write.
  *
  * Writes a size field in Flutter Standard encoding.
  */
@@ -23,11 +23,12 @@ void fl_standard_message_codec_write_size(FlStandardMessageCodec* codec,
 
 /**
  * fl_standard_message_codec_read_size:
- * @codec: a #FlStandardMessageCodec
- * @buffer: buffer to read from
- * @offset: (inout): read position in @buffer
- * @value: location to read size
- * @error: (allow-none): #GError location to store the error occurring, or %NULL
+ * @codec: an #FlStandardMessageCodec.
+ * @buffer: buffer to read from.
+ * @offset: (inout): read position in @buffer.
+ * @value: location to read size.
+ * @error: (allow-none): #GError location to store the error occurring, or
+ * %NULL.
  *
  * Reads a size field in Flutter Standard encoding.
  *
@@ -41,12 +42,13 @@ gboolean fl_standard_message_codec_read_size(FlStandardMessageCodec* codec,
 
 /**
  * fl_standard_message_codec_write_value:
- * @codec: a #FlStandardMessageCodec
- * @buffer: buffer to write into
- * @value: (allow-none): value to write
- * @error: (allow-none): #GError location to store the error occurring, or %NULL
+ * @codec: an #FlStandardMessageCodec.
+ * @buffer: buffer to write into.
+ * @value: (allow-none): value to write.
+ * @error: (allow-none): #GError location to store the error occurring, or
+ * %NULL.
  *
- * Writes a #FlValue in Flutter Standard encoding.
+ * Writes an #FlValue in Flutter Standard encoding.
  *
  * Returns: %TRUE on success.
  */
@@ -57,13 +59,14 @@ gboolean fl_standard_message_codec_write_value(FlStandardMessageCodec* codec,
 
 /**
  * fl_standard_message_codec_read_value:
- * @codec: a #FlStandardMessageCodec
- * @buffer: buffer to read from
- * @offset: (inout): read position in @buffer
- * @value: location to read size
- * @error: (allow-none): #GError location to store the error occurring, or %NULL
+ * @codec: an #FlStandardMessageCodec.
+ * @buffer: buffer to read from.
+ * @offset: (inout): read position in @buffer.
+ * @value: location to read size.
+ * @error: (allow-none): #GError location to store the error occurring, or
+ * %NULL.
  *
- * Reads a #FlValue in Flutter Standard encoding.
+ * Reads an #FlValue in Flutter Standard encoding.
  *
  * Returns: a new #FlValue or %NULL on error.
  */
diff --git a/shell/platform/linux/fl_string_codec_test.cc b/shell/platform/linux/fl_string_codec_test.cc
index f43589565..625736ca9 100644
--- a/shell/platform/linux/fl_string_codec_test.cc
+++ b/shell/platform/linux/fl_string_codec_test.cc
@@ -6,7 +6,7 @@
 #include "flutter/shell/platform/linux/testing/fl_test.h"
 #include "gtest/gtest.h"
 
-// Encode a message using a FlStringCodec. Return a hex string with the encoded
+// Encodes a message using a FlStringCodec. Return a hex string with the encoded
 // binary output.
 static gchar* encode_message(FlValue* value) {
   g_autoptr(FlStringCodec) codec = fl_string_codec_new();
@@ -19,7 +19,7 @@ static gchar* encode_message(FlValue* value) {
   return bytes_to_hex_string(message);
 }
 
-// Encode a message using a FlStringCodec. Expect the given error.
+// Encodes a message using a FlStringCodec. Expect the given error.
 static void encode_message_error(FlValue* value, GQuark domain, int code) {
   g_autoptr(FlStringCodec) codec = fl_string_codec_new();
   g_autoptr(GError) error = nullptr;
@@ -29,7 +29,7 @@ static void encode_message_error(FlValue* value, GQuark domain, int code) {
   EXPECT_TRUE(g_error_matches(error, domain, code));
 }
 
-// Decode a message using a FlStringCodec. The binary data is given in the form
+// Decodes a message using a FlStringCodec. The binary data is given in the form
 // of a hex string.
 static FlValue* decode_message(const char* hex_string) {
   g_autoptr(FlStringCodec) codec = fl_string_codec_new();
diff --git a/shell/platform/linux/fl_view.cc b/shell/platform/linux/fl_view.cc
index 49aa6d830..1c5bdbef9 100644
--- a/shell/platform/linux/fl_view.cc
+++ b/shell/platform/linux/fl_view.cc
@@ -15,9 +15,16 @@ static constexpr int kMicrosecondsPerMillisecond = 1000;
 struct _FlView {
   GtkWidget parent_instance;
 
+  // Project being run
   FlDartProject* project;
+
+  // Rendering output
   FlRendererX11* renderer;
+
+  // Engine running @project
   FlEngine* engine;
+
+  // Pointer button state recorded for sending status updates
   int64_t button_state;
 };
 
@@ -119,6 +126,7 @@ static void fl_view_dispose(GObject* object) {
   G_OBJECT_CLASS(fl_view_parent_class)->dispose(object);
 }
 
+// Implements GtkWidget::realize
 static void fl_view_realize(GtkWidget* widget) {
   FlView* self = FL_VIEW(widget);
 
@@ -155,6 +163,7 @@ static void fl_view_realize(GtkWidget* widget) {
     g_warning("Failed to start Flutter engine: %s", error->message);
 }
 
+// Implements GtkWidget::size-allocate
 static void fl_view_size_allocate(GtkWidget* widget,
                                   GtkAllocation* allocation) {
   FlView* self = FL_VIEW(widget);
@@ -171,6 +180,7 @@ static void fl_view_size_allocate(GtkWidget* widget,
                                       allocation->height, 1);
 }
 
+// Implements GtkWidget::button_press_event
 static gboolean fl_view_button_press_event(GtkWidget* widget,
                                            GdkEventButton* event) {
   FlView* self = FL_VIEW(widget);
@@ -183,6 +193,7 @@ static gboolean fl_view_button_press_event(GtkWidget* widget,
   return fl_view_send_pointer_button_event(self, event);
 }
 
+// Implements GtkWidget::button_release_event
 static gboolean fl_view_button_release_event(GtkWidget* widget,
                                              GdkEventButton* event) {
   FlView* self = FL_VIEW(widget);
@@ -190,6 +201,7 @@ static gboolean fl_view_button_release_event(GtkWidget* widget,
   return fl_view_send_pointer_button_event(self, event);
 }
 
+// Implements GtkWidget::motion_notify_event
 static gboolean fl_view_motion_notify_event(GtkWidget* widget,
                                             GdkEventMotion* event) {
   FlView* self = FL_VIEW(widget);
diff --git a/shell/platform/linux/public/flutter_linux/fl_basic_message_channel.h b/shell/platform/linux/public/flutter_linux/fl_basic_message_channel.h
index 5bdd5bb42..d5a966937 100644
--- a/shell/platform/linux/public/flutter_linux/fl_basic_message_channel.h
+++ b/shell/platform/linux/public/flutter_linux/fl_basic_message_channel.h
@@ -29,6 +29,49 @@ G_DECLARE_FINAL_TYPE(FlBasicMessageChannel,
  * #FlBasicMessageChannel is an object that allows sending and receiving
  * messages to/from Dart code over platform channels.
  *
+ * The following example shows how to send messages on a channel:
+ *
+ * |[<!-- language="C" -->
+ * static FlBasicMessageChannel *channel = NULL;
+ *
+ * static void message_cb (FlBasicMessageChannel* channel,
+ *                         FlValue* message,
+ *                         FlBasicMessageChannelResponseHandle* response_handle,
+ *                         gpointer user_data) {
+ *   g_autoptr(FlValue) response = handle_message (message);
+ *   g_autoptr(GError) error = NULL;
+ *   if (!fl_basic_message_channel_respond (channel, response_handle, response,
+ *                                          &error))
+ *     g_warning ("Failed to send channel response: %s", error->message);
+ * }
+ *
+ * static void message_response_cb (GObject *object,
+ *                                  GAsyncResult *result,
+ *                                  gpointer user_data) {
+ *   g_autoptr(GError) error = NULL;
+ *   g_autoptr(FlValue) response =
+ *     fl_basic_message_channel_send_finish (FL_BASIC_MESSAGE_CHANNEL (object),
+ *                                           result, &error);
+ *   if (response == NULL) {
+ *     g_warning ("Failed to send message: %s", error->message);
+ *     return;
+ *   }
+ *
+ *   handle_response (response);
+ * }
+ *
+ * static void setup_channel () {
+ *   g_autoptr(FlStandardMessageCodec) codec = fl_standard_message_codec_new ();
+ *   channel = fl_basic_message_channel_new (messenger, "flutter/foo",
+ *                                           FL_MESSAGE_CODEC (codec));
+ *   fl_basic_message_channel_set_message_handler (channel, message_cb, NULL);
+ *
+ *   g_autoptr(FlValue) message = fl_value_new_string ("Hello World");
+ *   fl_basic_message_channel_send (channel, message, NULL,
+ *                                  message_response_cb, NULL);
+ * }
+ * ]|
+ *
  * #FlBasicMessageChannel matches the BasicMessageChannel class in the Flutter
  * services library.
  */
@@ -43,10 +86,10 @@ typedef struct _FlBasicMessageChannelResponseHandle
 
 /**
  * FlBasicMessageChannelMessageHandler:
- * @channel: a #FlBasicMessageChannel
- * @message: message received
- * @response_handle: (transfer full): a handle to respond to the message with
- * @user_data: (closure): data provided when registering this handler
+ * @channel: an #FlBasicMessageChannel.
+ * @message: message received.
+ * @response_handle: (transfer full): a handle to respond to the message with.
+ * @user_data: (closure): data provided when registering this handler.
  *
  * Function called when a message is received.
  */
@@ -58,12 +101,12 @@ typedef void (*FlBasicMessageChannelMessageHandler)(
 
 /**
  * fl_basic_message_channel_new:
- * @messenger: a #FlBinaryMessenger
- * @name: a channel name
- * @codec: the message codec
+ * @messenger: an #FlBinaryMessenger.
+ * @name: a channel name.
+ * @codec: the message codec.
  *
- * Create a new basic message channel. @codec must match the codec used on the
- * Dart end of the channel.
+ * Creates a basic message channel. @codec must match the codec used on the Dart
+ * end of the channel.
  *
  * Returns: a new #FlBasicMessageChannel.
  */
@@ -74,12 +117,12 @@ FlBasicMessageChannel* fl_basic_message_channel_new(
 
 /**
  * fl_basic_message_channel_set_message_handler:
- * @channel: a #FlBasicMessageChannel
+ * @channel: an #FlBasicMessageChannel.
  * @handler: (allow-none): function to call when a message is received on this
  * channel or %NULL to disable the handler.
- * @user_data: (closure): user data to pass to @handler
+ * @user_data: (closure): user data to pass to @handler.
  *
- * Set the function called when a message is received.
+ * Sets the function called when a message is received.
  */
 void fl_basic_message_channel_set_message_handler(
     FlBasicMessageChannel* channel,
@@ -88,15 +131,15 @@ void fl_basic_message_channel_set_message_handler(
 
 /**
  * fl_basic_message_channel_respond:
- * @channel: a #FlBasicMessageChannel
+ * @channel: an #FlBasicMessageChannel.
  * @response_handle: (transfer full): handle that was provided in a
- * #FlBasicMessageChannelMessageHandler
+ * #FlBasicMessageChannelMessageHandler.
  * @message: (allow-none): message response to send or %NULL for an empty
- * response
+ * response.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
- * to ignore
+ * to ignore.
  *
- * Respond to a message.
+ * Responds to a message.
  *
  * Returns: %TRUE on success.
  */
@@ -108,14 +151,14 @@ gboolean fl_basic_message_channel_respond(
 
 /**
  * fl_basic_message_channel_send:
- * @channel: a #FlBasicMessageChannel
- * @message: message to send, must match what the #FlMessageCodec supports
- * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @channel: an #FlBasicMessageChannel.
+ * @message: message to send, must match what the #FlMessageCodec supports.
+ * @cancellable: (allow-none): a #GCancellable or %NULL.
  * @callback: (scope async): (allow-none): a #GAsyncReadyCallback to call when
  * the request is satisfied or %NULL to ignore the response.
- * @user_data: (closure): user data to pass to @callback
+ * @user_data: (closure): user data to pass to @callback.
  *
- * Asynchronously send a message.
+ * Asynchronously sends a message.
  */
 void fl_basic_message_channel_send(FlBasicMessageChannel* channel,
                                    FlValue* message,
@@ -125,12 +168,12 @@ void fl_basic_message_channel_send(FlBasicMessageChannel* channel,
 
 /**
  * fl_basic_message_channel_send_finish:
- * @channel: a #FlBasicMessageChannel
- * @result: a #GAsyncResult
+ * @channel: an #FlBasicMessageChannel.
+ * @result: a #GAsyncResult.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
- * Complete request started with fl_basic_message_channel_send().
+ * Completes request started with fl_basic_message_channel_send().
  *
  * Returns: message response on success or %NULL on error.
  */
diff --git a/shell/platform/linux/public/flutter_linux/fl_binary_codec.h b/shell/platform/linux/public/flutter_linux/fl_binary_codec.h
index 00e727d09..e7223d8df 100644
--- a/shell/platform/linux/public/flutter_linux/fl_binary_codec.h
+++ b/shell/platform/linux/public/flutter_linux/fl_binary_codec.h
@@ -23,8 +23,9 @@ G_DECLARE_FINAL_TYPE(FlBinaryCodec,
  * FlBinaryCodec:
  *
  * #FlBinaryCodec is an #FlMessageCodec that implements the Flutter binary
- * message encoding. This encodes and decodes #FlValue of type
- * #FL_VALUE_TYPE_UINT8_LIST.
+ * message encoding. This only encodes and decodes #FlValue of type
+ * #FL_VALUE_TYPE_UINT8_LIST, other types #FlValues will generate an error
+ * during encoding.
  *
  * #FlBinaryCodec matches the BinaryCodec class in the Flutter services
  * library.
@@ -33,7 +34,7 @@ G_DECLARE_FINAL_TYPE(FlBinaryCodec,
 /**
  * fl_binary_codec_new:
  *
- * Creates a #FlBinaryCodec.
+ * Creates an #FlBinaryCodec.
  *
  * Returns: a new #FlBinaryCodec.
  */
diff --git a/shell/platform/linux/public/flutter_linux/fl_binary_messenger.h b/shell/platform/linux/public/flutter_linux/fl_binary_messenger.h
index a14447149..c29e97892 100644
--- a/shell/platform/linux/public/flutter_linux/fl_binary_messenger.h
+++ b/shell/platform/linux/public/flutter_linux/fl_binary_messenger.h
@@ -24,7 +24,7 @@ G_DECLARE_FINAL_TYPE(FlBinaryMessenger,
  * FlBinaryMessenger:
  *
  * #FlBinaryMessenger is an object that allows sending and receiving of platform
- * messages with a #FlEngine.
+ * messages with an #FlEngine.
  */
 
 /**
@@ -36,11 +36,11 @@ typedef struct _FlBinaryMessengerResponseHandle FlBinaryMessengerResponseHandle;
 
 /**
  * FlBinaryMessengerMessageHandler:
- * @messenger: a #FlBinaryMessenger
- * @channel: channel message received on
- * @message: message content received from Dart
- * @response_handle: (transfer full): a handle to respond to the message with
- * @user_data: (closure): data provided when registering this handler
+ * @messenger: an #FlBinaryMessenger.
+ * @channel: channel message received on.
+ * @message: message content received from Dart.
+ * @response_handle: (transfer full): a handle to respond to the message with.
+ * @user_data: (closure): data provided when registering this handler.
  *
  * Function called when platform messages are received. The receiver must
  * call fl_binary_messenger_send_response() to avoid leaking the handle.
@@ -54,13 +54,13 @@ typedef void (*FlBinaryMessengerMessageHandler)(
 
 /**
  * fl_binary_messenger_set_platform_message_handler:
- * @binary_messenger: a #FlBinaryMessenger
- * @channel: channel to listen on
+ * @binary_messenger: an #FlBinaryMessenger.
+ * @channel: channel to listen on.
  * @handler: (allow-none): function to call when a message is received on this
  * channel or %NULL to disable a handler
- * @user_data: (closure): user data to pass to @handler
+ * @user_data: (closure): user data to pass to @handler.
  *
- * Set the function called when a platform message is received on the given
+ * Sets the function called when a platform message is received on the given
  * channel. Call fl_binary_messenger_send_response() when the message is
  * handled. Ownership of #FlBinaryMessengerResponseHandle is transferred to the
  * caller, and the call must be responded to to avoid memory leaks.
@@ -73,14 +73,14 @@ void fl_binary_messenger_set_message_handler_on_channel(
 
 /**
  * fl_binary_messenger_send_response:
- * @binary_messenger: a #FlBinaryMessenger
+ * @binary_messenger: an #FlBinaryMessenger.
  * @response_handle: (transfer full): handle that was provided in a
- * #FlBinaryMessengerMessageHandler
- * @response: (allow-none): response to send or %NULL for an empty response
+ * #FlBinaryMessengerMessageHandler.
+ * @response: (allow-none): response to send or %NULL for an empty response.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
- * to ignore
+ * to ignore.
  *
- * Respond to a platform message.
+ * Responds to a platform message.
  *
  * Returns: %TRUE on success.
  */
@@ -92,15 +92,15 @@ gboolean fl_binary_messenger_send_response(
 
 /**
  * fl_binary_messenger_send_on_channel:
- * @binary_messenger: a #FlBinaryMessenger
- * @channel: channel to send to
- * @message: (allow-none): message buffer to send or %NULL for an empty message
- * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @binary_messenger: an #FlBinaryMessenger.
+ * @channel: channel to send to.
+ * @message: (allow-none): message buffer to send or %NULL for an empty message.
+ * @cancellable: (allow-none): a #GCancellable or %NULL.
  * @callback: (scope async): a #GAsyncReadyCallback to call when the request is
- * satisfied
- * @user_data: (closure): user data to pass to @callback
+ * satisfied.
+ * @user_data: (closure): user data to pass to @callback.
  *
- * Asynchronously send a platform message.
+ * Asynchronously sends a platform message.
  */
 void fl_binary_messenger_send_on_channel(FlBinaryMessenger* messenger,
                                          const gchar* channel,
@@ -111,14 +111,14 @@ void fl_binary_messenger_send_on_channel(FlBinaryMessenger* messenger,
 
 /**
  * fl_binary_messenger_send_on_channel_finish:
- * @binary_messenger: a #FlBinaryMessenger
- * @result: a #GAsyncResult
+ * @binary_messenger: an #FlBinaryMessenger.
+ * @result: a #GAsyncResult.
  * @error: (allow-none): #GError location to store the error occurring, or %NULL
  * to ignore.
  *
- * Complete request started with fl_binary_messenger_send_on_channel().
+ * Completes request started with fl_binary_messenger_send_on_channel().
  *
- * Returns: message response on success or %NULL on error.
+ * Returns: (transfer full): message response on success or %NULL on error.
  */
 GBytes* fl_binary_messenger_send_on_channel_finish(FlBinaryMessenger* messenger,
                                                    GAsyncResult* result,
diff --git a/shell/platform/linux/public/flutter_linux/fl_dart_project.h b/shell/platform/linux/public/flutter_linux/fl_dart_project.h
index 970618c35..e82f6ac1a 100644
--- a/shell/platform/linux/public/flutter_linux/fl_dart_project.h
+++ b/shell/platform/linux/public/flutter_linux/fl_dart_project.h
@@ -19,14 +19,14 @@ G_DECLARE_FINAL_TYPE(FlDartProject, fl_dart_project, FL, DART_PROJECT, GObject)
  * FlDartProject:
  *
  * #FlDartProject represents a Dart project. It is used to provide information
- * about the application when creating a #FlView.
+ * about the application when creating an #FlView.
  */
 
 /**
  * fl_dart_project_new:
- * @path: a file path, e.g. "my_dart_project"
+ * @path: a file path, e.g. "my_dart_project".
  *
- * Create a Flutter project. The project path should contain the following
+ * Creates a Flutter project. The project path should contain the following
  * top-level items:
  * - icudtl.dat (provided as a resource by the Flutter tool)
  * - flutter_assets (as built by the Flutter tool)
@@ -34,12 +34,12 @@ G_DECLARE_FINAL_TYPE(FlDartProject, fl_dart_project, FL, DART_PROJECT, GObject)
  * The path can either be absolute, or relative to the directory containing the
  * running executable.
  *
- * Returns: a new #FlDartProject
+ * Returns: a new #FlDartProject.
  */
 
 /**
  * fl_dart_project_new:
- * @path: a file path, e.g. "my_dart_project"
+ * @path: (type filename): a file path, e.g. "my_dart_project".
  *
  * Creates a Flutter project. The project path should contain the following
  * top-level items:
@@ -49,40 +49,40 @@ G_DECLARE_FINAL_TYPE(FlDartProject, fl_dart_project, FL, DART_PROJECT, GObject)
  * The path can either be absolute, or relative to the directory containing the
  * running executable.
  *
- * Returns: a new #FlDartProject
+ * Returns: a new #FlDartProject.
  */
 FlDartProject* fl_dart_project_new(const gchar* path);
 
 /**
  * fl_dart_project_get_path:
- * @project: a #FlDartProject
+ * @project: an #FlDartProject.
  *
  * Gets the path to the directory containing the Flutter application.
  *
- * Returns: (type filename): a file path, e.g. "/projects/my_dart_project"
+ * Returns: (type filename): a file path, e.g. "/projects/my_dart_project".
  */
 const gchar* fl_dart_project_get_path(FlDartProject* project);
 
 /**
  * fl_dart_project_get_assets_path:
- * @project: a #FlDartProject
+ * @project: an #FlDartProject.
  *
  * Gets the path to the directory containing the assets used in the Flutter
  * application.
  *
  * Returns: (type filename): a file path, e.g.
- * "/projects/my_dart_project/flutter_assets"
+ * "/projects/my_dart_project/flutter_assets".
  */
 gchar* fl_dart_project_get_assets_path(FlDartProject* project);
 
 /**
  * fl_dart_project_get_icu_data_path:
- * @project: a #FlDartProject
+ * @project: an #FlDartProject.
  *
  * Gets the path to the ICU data file in the Flutter application.
  *
  * Returns: (type filename): a file path, e.g.
- * "/projects/my_dart_project/icudtl.dat"
+ * "/projects/my_dart_project/icudtl.dat".
  */
 gchar* fl_dart_project_get_icu_data_path(FlDartProject* project);
 
diff --git a/shell/platform/linux/public/flutter_linux/fl_engine.h b/shell/platform/linux/public/flutter_linux/fl_engine.h
index 947371797..629972287 100644
--- a/shell/platform/linux/public/flutter_linux/fl_engine.h
+++ b/shell/platform/linux/public/flutter_linux/fl_engine.h
@@ -26,11 +26,11 @@ G_DECLARE_FINAL_TYPE(FlEngine, fl_engine, FL, ENGINE, GObject)
 
 /**
  * fl_engine_get_binary_messenger:
- * @engine: a #FlEngine
+ * @engine: an #FlEngine.
  *
- * Get the messenger to communicate with this engine.
+ * Gets the messenger to communicate with this engine.
  *
- * Returns: a #FlBinaryMessenger
+ * Returns: an #FlBinaryMessenger.
  */
 FlBinaryMessenger* fl_engine_get_binary_messenger(FlEngine* engine);
 
diff --git a/shell/platform/linux/public/flutter_linux/fl_json_message_codec.h b/shell/platform/linux/public/flutter_linux/fl_json_message_codec.h
index 5796ffecd..ddf68189a 100644
--- a/shell/platform/linux/public/flutter_linux/fl_json_message_codec.h
+++ b/shell/platform/linux/public/flutter_linux/fl_json_message_codec.h
@@ -17,7 +17,8 @@ G_BEGIN_DECLS
  * FlJsonMessageCodecError:
  * @FL_JSON_MESSAGE_CODEC_ERROR_INVALID_UTF8: Message is not valid UTF-8.
  * @FL_JSON_MESSAGE_CODEC_ERROR_INVALID_JSON: Message is not valid JSON.
- * @FL_JSON_MESSAGE_CODEC_ERROR_INVALID_OBJECT_KEY_TYPE: Invalid object key type
+ * @FL_JSON_MESSAGE_CODEC_ERROR_INVALID_OBJECT_KEY_TYPE: Invalid object key
+ * type.
  *
  * Errors for #FlJsonMessageCodec objects to set on failures.
  */
@@ -40,12 +41,12 @@ G_DECLARE_FINAL_TYPE(FlJsonMessageCodec,
 /**
  * FlJsonMessageCodec:
  *
- * #FlJsonMessageCodec is an #FlMessageCodec that implements the Flutter
- * standard message encoding. This encodes and decodes #FlValue of type
+ * #FlJsonMessageCodec is an #FlMessageCodec that implements the encodes
+ * #FlValue to/from JSON. This codec encodes and decodes #FlValue of type
  * #FL_VALUE_TYPE_NULL, #FL_VALUE_TYPE_BOOL, #FL_VALUE_TYPE_INT,
  * #FL_VALUE_TYPE_FLOAT, #FL_VALUE_TYPE_STRING, #FL_VALUE_TYPE_UINT8_LIST,
  * #FL_VALUE_TYPE_INT32_LIST, #FL_VALUE_TYPE_INT64_LIST,
- * #FL_VALUE_TYPE_FLOAT_LIST, #FL_VALUE_TYPE_LIST, and #FL_VALUE_TYPE_MAP
+ * #FL_VALUE_TYPE_FLOAT_LIST, #FL_VALUE_TYPE_LIST, and #FL_VALUE_TYPE_MAP.
  *
  * #FlJsonMessageCodec matches the JSONMessageCodec class in the Flutter
  * services library.
@@ -54,19 +55,20 @@ G_DECLARE_FINAL_TYPE(FlJsonMessageCodec,
 /**
  * fl_json_message_codec_new:
  *
- * Creates a #FlJsonMessageCodec.
+ * Creates an #FlJsonMessageCodec.
  *
- * Returns: a new #FlJsonMessageCodec
+ * Returns: a new #FlJsonMessageCodec.
  */
 FlJsonMessageCodec* fl_json_message_codec_new();
 
 /**
  * fl_json_message_codec_encode:
- * @codec: a #FlJsonMessageCodec
- * @value: value to encode
- * @error: (allow-none): #GError location to store the error occurring, or %NULL
+ * @codec: an #FlJsonMessageCodec.
+ * @value: value to encode.
+ * @error: (allow-none): #GError location to store the error occurring, or
+ * %NULL.
  *
- * Encode a value to a JSON string.
+ * Encodes a value to a JSON string.
  *
  * Returns: a JSON representation of this value or %NULL on error.
  */
@@ -76,13 +78,14 @@ gchar* fl_json_message_codec_encode(FlJsonMessageCodec* codec,
 
 /**
  * fl_json_message_codec_decode:
- * @codec: a #FlJsonMessageCodec
- * @text: UTF-8 text in JSON format
- * @error: (allow-none): #GError location to store the error occurring, or %NULL
+ * @codec: an #FlJsonMessageCodec.
+ * @text: UTF-8 text in JSON format.
+ * @error: (allow-none): #GError location to store the error occurring, or
+ * %NULL.
  *
- * Decode a value from a JSON string.
+ * Decodes a value from a JSON string.
  *
- * Returns: a #FlValue or %NULL on error
+ * Returns: an #FlValue or %NULL on error.
  */
 FlValue* fl_json_message_codec_decode(FlJsonMessageCodec* codec,
                                       const gchar* text,
diff --git a/shell/platform/linux/public/flutter_linux/fl_message_codec.h b/shell/platform/linux/public/flutter_linux/fl_message_codec.h
index 03e17db7a..b74aad264 100644
--- a/shell/platform/linux/public/flutter_linux/fl_message_codec.h
+++ b/shell/platform/linux/public/flutter_linux/fl_message_codec.h
@@ -17,12 +17,12 @@ G_BEGIN_DECLS
 
 /**
  * FlMessageCodecError:
- * @FL_MESSAGE_CODEC_ERROR_FAILED: Codec failed due to an unspecified error
- * @FL_MESSAGE_CODEC_ERROR_OUT_OF_DATA: Codec ran out of data reading a value
+ * @FL_MESSAGE_CODEC_ERROR_FAILED: Codec failed due to an unspecified error.
+ * @FL_MESSAGE_CODEC_ERROR_OUT_OF_DATA: Codec ran out of data reading a value.
  * @FL_MESSAGE_CODEC_ERROR_ADDITIONAL_DATA: Additional data encountered in
- * message
+ * message.
  * @FL_MESSAGE_CODEC_ERROR_UNSUPPORTED_TYPE: Codec encountered an unsupported
- * #FlValue
+ * #FlValue.
  *
  * Errors for #FlMessageCodec objects to set on failures.
  */
@@ -59,10 +59,10 @@ struct _FlMessageCodecClass {
 
   /**
    * FlMessageCodec::encode_message:
-   * @codec: A #FlMessageCodec
-   * @message: message to encode or %NULL to encode the null value
+   * @codec: A #FlMessageCodec.
+   * @message: message to encode or %NULL to encode the null value.
    * @error: (allow-none): #GError location to store the error occurring, or
-   * %NULL
+   * %NULL.
    *
    * Virtual method to encode a message. A subclass must implement this method.
    * If the subclass cannot handle the type of @message then it must generate a
@@ -76,17 +76,17 @@ struct _FlMessageCodecClass {
 
   /**
    * FlMessageCodec::decode_message:
-   * @codec: a #FlMessageCodec
-   * @message: binary message to decode
+   * @codec: an #FlMessageCodec.
+   * @message: binary message to decode.
    * @error: (allow-none): #GError location to store the error occurring, or
-   * %NULL
+   * %NULL.
    *
    * Virtual method to decode a message. A subclass must implement this method.
    * If @message is too small then a #FL_MESSAGE_CODEC_ERROR_OUT_OF_DATA error
    * must be generated. If @message is too large then a
    * #FL_MESSAGE_CODEC_ERROR_ADDITIONAL_DATA error must be generated.
    *
-   * Returns: a #FlValue or %NULL on error.
+   * Returns: an #FlValue or %NULL on error.
    */
   FlValue* (*decode_message)(FlMessageCodec* codec,
                              GBytes* message,
@@ -95,14 +95,15 @@ struct _FlMessageCodecClass {
 
 /**
  * fl_message_codec_encode_message:
- * @codec: a #FlMessageCodec
- * @buffer: buffer to write to
+ * @codec: an #FlMessageCodec.
+ * @buffer: buffer to write to.
  * @message: message to encode or %NULL to encode the null value.
- * @error: (allow-none): #GError location to store the error occurring, or %NULL
+ * @error: (allow-none): #GError location to store the error occurring, or
+ * %NULL.
  *
- * Encode a message into a binary representation.
+ * Encodes a message into a binary representation.
  *
- * Returns: a binary message or %NULL on error.
+ * Returns: a binary encoded message or %NULL on error.
  */
 GBytes* fl_message_codec_encode_message(FlMessageCodec* codec,
                                         FlValue* message,
@@ -110,13 +111,14 @@ GBytes* fl_message_codec_encode_message(FlMessageCodec* codec,
 
 /**
  * fl_message_codec_decode_message:
- * @codec: a #FlMessageCodec
- * @message: binary message to decode
- * @error: (allow-none): #GError location to store the error occurring, or %NULL
+ * @codec: an #FlMessageCodec.
+ * @message: binary message to decode.
+ * @error: (allow-none): #GError location to store the error occurring, or
+ * %NULL.
  *
- * Decode a message from a binary encoding.
+ * Decodes a message from a binary encoding.
  *
- * Returns: a #FlValue or %NULL on error.
+ * Returns: an #FlValue or %NULL on error.
  */
 FlValue* fl_message_codec_decode_message(FlMessageCodec* codec,
                                          GBytes* message,
diff --git a/shell/platform/linux/public/flutter_linux/fl_standard_message_codec.h b/shell/platform/linux/public/flutter_linux/fl_standard_message_codec.h
index 5ba56ce62..2af7b83b8 100644
--- a/shell/platform/linux/public/flutter_linux/fl_standard_message_codec.h
+++ b/shell/platform/linux/public/flutter_linux/fl_standard_message_codec.h
@@ -23,11 +23,11 @@ G_DECLARE_FINAL_TYPE(FlStandardMessageCodec,
  * FlStandardMessageCodec:
  *
  * #FlStandardMessageCodec is an #FlMessageCodec that implements the Flutter
- * standard message encoding. This encodes and decodes #FlValue of type
+ * standard message encoding. This codec encodes and decodes #FlValue of type
  * #FL_VALUE_TYPE_NULL, #FL_VALUE_TYPE_BOOL, #FL_VALUE_TYPE_INT,
  * #FL_VALUE_TYPE_FLOAT, #FL_VALUE_TYPE_STRING, #FL_VALUE_TYPE_UINT8_LIST,
  * #FL_VALUE_TYPE_INT32_LIST, #FL_VALUE_TYPE_INT64_LIST,
- * #FL_VALUE_TYPE_FLOAT_LIST, #FL_VALUE_TYPE_LIST, and #FL_VALUE_TYPE_MAP
+ * #FL_VALUE_TYPE_FLOAT_LIST, #FL_VALUE_TYPE_LIST, and #FL_VALUE_TYPE_MAP.
  *
  * #FlStandardMessageCodec matches the StandardCodec class in the Flutter
  * services library.
@@ -36,9 +36,9 @@ G_DECLARE_FINAL_TYPE(FlStandardMessageCodec,
 /*
  * fl_standard_message_codec_new:
  *
- * Creates a #FlStandardMessageCodec.
+ * Creates an #FlStandardMessageCodec.
  *
- * Returns: a new #FlStandardMessageCodec
+ * Returns: a new #FlStandardMessageCodec.
  */
 FlStandardMessageCodec* fl_standard_message_codec_new();
 
diff --git a/shell/platform/linux/public/flutter_linux/fl_string_codec.h b/shell/platform/linux/public/flutter_linux/fl_string_codec.h
index 8778046d7..8f49e9fe0 100644
--- a/shell/platform/linux/public/flutter_linux/fl_string_codec.h
+++ b/shell/platform/linux/public/flutter_linux/fl_string_codec.h
@@ -23,8 +23,9 @@ G_DECLARE_FINAL_TYPE(FlStringCodec,
  * FlStringCodec:
  *
  * #FlStringCodec is an #FlMessageCodec that implements the Flutter string
- * message encoding. This encodes and decodes #FlValue of type
- * #FL_VALUE_TYPE_STRING.
+ * message encoding. This only encodes and decodes #FlValue of type
+ * #FL_VALUE_TYPE_STRING, other types #FlValues will generate an error during
+ * encoding.
  *
  * #FlStringCodec matches the StringCodec class in the Flutter services library.
  */
@@ -32,7 +33,7 @@ G_DECLARE_FINAL_TYPE(FlStringCodec,
 /**
  * fl_string_codec_new:
  *
- * Creates a #FlStringCodec.
+ * Creates an #FlStringCodec.
  *
  * Returns: a new #FlStringCodec.
  */
diff --git a/shell/platform/linux/public/flutter_linux/fl_value.h b/shell/platform/linux/public/flutter_linux/fl_value.h
index f624bad73..4f0ffd3c9 100644
--- a/shell/platform/linux/public/flutter_linux/fl_value.h
+++ b/shell/platform/linux/public/flutter_linux/fl_value.h
@@ -19,7 +19,7 @@ G_BEGIN_DECLS
  * FlValue:
  *
  * #FlValue is an object that contains the data types used in the platform
- * channel codecs provided by Flutter.
+ * channel used by Flutter.
  *
  * In Dart the values are represented as follows:
  * - #FL_VALUE_TYPE_NULL: null
@@ -34,7 +34,7 @@ G_BEGIN_DECLS
  * - #FL_VALUE_TYPE_LIST: List
  * - #FL_VALUE_TYPE_MAP: Map
  *
- * See #FlMessageCodec to encode and decode these values to a binary form.
+ * See #FlMessageCodec to encode and decode these values.
  */
 typedef struct _FlValue FlValue;
 
@@ -71,7 +71,8 @@ typedef enum {
 /**
  * fl_value_new_null:
  *
- * Creates an #FlValue that contains a null value.
+ * Creates an #FlValue that contains a null value. The equivalent Dart type is
+ * null.
  *
  * Returns: a new #FlValue.
  */
@@ -81,7 +82,8 @@ FlValue* fl_value_new_null();
  * fl_value_new_bool:
  * @value: the value.
  *
- * Creates an #FlValue that contains a boolean value.
+ * Creates an #FlValue that contains a boolean value. The equivalent Dart type
+ * is a bool.
  *
  * Returns: a new #FlValue.
  */
@@ -91,7 +93,8 @@ FlValue* fl_value_new_bool(bool value);
  * fl_value_new_int:
  * @value: the value.
  *
- * Creates an #FlValue that contains an integer number.
+ * Creates an #FlValue that contains an integer number. The equivalent Dart type
+ * is a num.
  *
  * Returns: a new #FlValue.
  */
@@ -101,7 +104,8 @@ FlValue* fl_value_new_int(int64_t value);
  * fl_value_new_float:
  * @value: the value.
  *
- * Creates an #FlValue that contains a floating point number.
+ * Creates an #FlValue that contains a floating point number. The equivalent
+ * Dart type is a num.
  *
  * Returns: a new #FlValue.
  */
@@ -111,7 +115,8 @@ FlValue* fl_value_new_float(double value);
  * fl_value_new_string:
  * @value: a nul terminated UTF-8 string.
  *
- * Creates an #FlValue that contains UTF-8 text.
+ * Creates an #FlValue that contains UTF-8 text. The equivalent Dart type is a
+ * String.
  *
  * Returns: a new #FlValue.
  */
@@ -122,7 +127,8 @@ FlValue* fl_value_new_string(const gchar* value);
  * @value: a buffer containing UTF-8 text. It does not require a nul terminator.
  * @value_length: the number of bytes to use from @value.
  *
- * Creates an #FlValue that contains UTF-8 text.
+ * Creates an #FlValue that contains UTF-8 text. The equivalent Dart type is a
+ * String.
  *
  * Returns: a new #FlValue.
  */
@@ -130,58 +136,88 @@ FlValue* fl_value_new_string_sized(const gchar* value, size_t value_length);
 
 /**
  * fl_value_new_uint8_list:
- * @data: Data to copy.
- * @data_length: number of elements in @data.
+ * @value: an arrary of unsigned 8 bit integers.
+ * @value_length: number of elements in @value.
  *
- * Creates an ordered list containing 8 bit unsigned integers.
+ * Creates an ordered list containing 8 bit unsigned integers. The data is
+ * copied. The equivalent Dart type is a Uint8List.
  *
  * Returns: a new #FlValue.
  */
-FlValue* fl_value_new_uint8_list(const uint8_t* data, size_t data_length);
+FlValue* fl_value_new_uint8_list(const uint8_t* value, size_t value_length);
 
 /**
  * fl_value_new_uint8_list:
- * @data: Data to copy
+ * @value: a #GBytes.
  *
- * Creates an ordered list containing 8 bit unsigned integers.
+ * Creates an ordered list containing 8 bit unsigned integers. The data is
+ * copied. The equivalent Dart type is a Uint8List.
  *
  * Returns: a new #FlValue.
  */
-FlValue* fl_value_new_uint8_list_from_bytes(GBytes* data);
+FlValue* fl_value_new_uint8_list_from_bytes(GBytes* value);
 
 /**
  * fl_value_new_int32_list:
+ * @value: an arrary of signed 32 bit integers.
+ * @value_length: number of elements in @value.
  *
- * Creates an ordered list containing 32 bit integers.
+ * Creates an ordered list containing 32 bit integers. The equivalent Dart type
+ * is a Int32List.
  *
  * Returns: a new #FlValue.
  */
-FlValue* fl_value_new_int32_list(const int32_t* data, size_t data_length);
+FlValue* fl_value_new_int32_list(const int32_t* value, size_t value_length);
 
 /**
  * fl_value_new_int64_list:
+ * @value: an arrary of signed 64 bit integers.
+ * @value_length: number of elements in @value.
  *
- * Creates an ordered list containing 64 bit integers.
+ * Creates an ordered list containing 64 bit integers. The equivalent Dart type
+ * is a Int64List.
  *
  * Returns: a new #FlValue.
  */
-FlValue* fl_value_new_int64_list(const int64_t* data, size_t data_length);
+FlValue* fl_value_new_int64_list(const int64_t* value, size_t value_length);
 
 /**
  * fl_value_new_float_list:
+ * @value: an arrary of floating point numbers.
+ * @value_length: number of elements in @value.
  *
- * Creates an ordered list containing floating point numbers.
+ * Creates an ordered list containing floating point numbers. The equivalent
+ * Dart type is a Float64List.
  *
  * Returns: a new #FlValue.
  */
-FlValue* fl_value_new_float_list(const double* data, size_t data_length);
+FlValue* fl_value_new_float_list(const double* value, size_t value_length);
 
 /**
  * fl_value_new_list:
  *
  * Creates an ordered list. Children can be added to the list using
  * fl_value_append(). The children are accessed using fl_value_get_length()
- * and fl_value_get_list_value().
+ * and fl_value_get_list_value(). The equivalent Dart type is a List.
+ *
+ * The following example shows a simple list of values:
+ *
+ * |[<!-- language="C" -->
+ *   g_autoptr(FlValue) value = fl_value_new_list ();
+ *   fl_value_append_take (value, fl_value_new_string ("one");
+ *   fl_value_append_take (value, fl_value_new_int (2);
+ *   fl_value_append_take (value, fl_value_new_double (3.0);
+ * ]|
+ *
+ * This value can be decoded using:
+ *
+ * |[<!-- language="C" -->
+ *   g_assert (fl_value_get_type (value) == FL_VALUE_TYPE_LIST);
+ *   for (size_t i = 0; i < fl_value_get_length (value); i++) {
+ *     FlValue *child = fl_value_get_list_value (value, i);
+ *     process_value (child);
+ *   }
+ * ]|
  *
  * Returns: a new #FlValue.
  */
@@ -189,13 +225,13 @@ FlValue* fl_value_new_list();
 
 /**
  * fl_value_new_list_from_strv:
- * @str_array: a %NULL-terminated array of strings.
+ * @value: a %NULL-terminated array of strings.
  *
  * Creates an ordered list containing #FlString values.
  *
  * Returns: a new #FlValue.
  */
-FlValue* fl_value_new_list_from_strv(const gchar* const* str_array);
+FlValue* fl_value_new_list_from_strv(const gchar* const* value);
 
 /**
  * fl_value_new_map:
@@ -204,7 +240,30 @@ FlValue* fl_value_new_list_from_strv(const gchar* const* str_array);
  * using fl_value_set(), fl_value_set_take(), fl_value_set_string(),
  * fl_value_set_string_take(). The children are accessed using
  * fl_value_get_length(), fl_value_get_map_key(), fl_value_get_map_value(),
- * fl_value_lookup() and fl_value_lookup_string().
+ * fl_value_lookup() and fl_value_lookup_string(). The equivalent Dart type is a
+ * Map.
+ *
+ * The following example shows how to create a map of values keyed by strings:
+ *
+ * |[<!-- language="C" -->
+ *   g_autoptr(FlValue) value = fl_value_new_map ();
+ *   fl_value_set_string_take (value, "name", fl_value_new_string ("Gandalf"));
+ *   fl_value_set_string_take (value, "occupation",
+ *                             fl_value_new_string ("Wizard"));
+ *   fl_value_set_string_take (value, "age", fl_value_new_int (2019));
+ * ]|
+ *
+ * This value can be decoded using:
+ * |[<!-- language="C" -->
+ *   g_assert (fl_value_get_type (value) == FL_VALUE_TYPE_MAP);
+ *   FlValue *name = fl_value_lookup_string (value, "name");
+ *   g_assert (fl_value_get_type (name) == FL_VALUE_TYPE_STRING);
+ *   FlValue *age = fl_value_lookup_string (value, "age");
+ *   g_assert (fl_value_get_type (age) == FL_VALUE_TYPE_INT);
+ *   g_message ("Next customer is %s (%d years old)",
+ *              fl_value_get_string (name),
+ *              fl_value_get_int (age));
+ * ]|
  *
  * Returns: a new #FlValue.
  */
@@ -212,7 +271,7 @@ FlValue* fl_value_new_map();
 
 /**
  * fl_value_ref:
- * @value: an #FlValue
+ * @value: an #FlValue.
  *
  * Increases the reference count of an #FlValue.
  *
@@ -221,8 +280,8 @@ FlValue* fl_value_new_map();
 FlValue* fl_value_ref(FlValue* value);
 
 /**
- * fl_value_ref:
- * @value: an #FlValue
+ * fl_value_unref:
+ * @value: an #FlValue.
  *
  * Dereases the reference count of an #FlValue. When the refernece count hits
  * zero @value is destroyed and no longer valid.
@@ -231,7 +290,7 @@ void fl_value_unref(FlValue* value);
 
 /**
  * fl_value_get_type:
- * @value: an #FlValue
+ * @value: an #FlValue.
  *
  * Gets the type of @value.
  *
@@ -241,8 +300,8 @@ FlValueType fl_value_get_type(FlValue* value);
 
 /**
  * fl_value_equal:
- * @a: an #FlValue
- * @b: an #FlValue
+ * @a: an #FlValue.
+ * @b: an #FlValue.
  *
  * Compares two #FlValue to see if they are equivalent. Two values are
  * considered equivalent if they are of the same type and their data is the same
@@ -255,8 +314,8 @@ bool fl_value_equal(FlValue* a, FlValue* b);
 
 /**
  * fl_value_append:
- * @value: an #FlValue of type #FL_VALUE_TYPE_LIST
- * @child: an #FlValue
+ * @value: an #FlValue of type #FL_VALUE_TYPE_LIST.
+ * @child: an #FlValue.
  *
  * Adds @child to the end of @value. Calling this with an #FlValue that is not
  * of type #FL_VALUE_TYPE_LIST is a programming error.
@@ -265,8 +324,8 @@ void fl_value_append(FlValue* value, FlValue* child);
 
 /**
  * fl_value_append:
- * @value: an #FlValue of type #FL_VALUE_TYPE_LIST
- * @child: (transfer full): an #FlValue
+ * @value: an #FlValue of type #FL_VALUE_TYPE_LIST.
+ * @child: (transfer full): an #FlValue.
  *
  * Adds @child to the end of @value. Ownership of @child is taken by @value.
  * Calling this with an #FlValue that is not of type #FL_VALUE_TYPE_LIST is a
@@ -276,9 +335,9 @@ void fl_value_append_take(FlValue* value, FlValue* child);
 
 /**
  * fl_value_set:
- * @value: an #FlValue of type #FL_VALUE_TYPE_MAP
- * @key: an #FlValue
- * @child_value: an #FlValue
+ * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
+ * @key: an #FlValue.
+ * @child_value: an #FlValue.
  *
  * Sets @key in @value to @child_value. If an existing value was in the map with
  * the same key it is replaced. Calling this with an #FlValue that is not of
@@ -288,9 +347,9 @@ void fl_value_set(FlValue* value, FlValue* key, FlValue* child_value);
 
 /**
  * fl_value_set_take:
- * @value: an #FlValue of type #FL_VALUE_TYPE_MAP
- * @key: (transfer full): an #FlValue
- * @child_value: (transfer full): an #FlValue
+ * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
+ * @key: (transfer full): an #FlValue.
+ * @child_value: (transfer full): an #FlValue.
  *
  * Sets @key in @value to @child_value. Ownership of both @key and @child_value
  * is taken by @value. If an existing value was in the map with the same key it
@@ -301,9 +360,9 @@ void fl_value_set_take(FlValue* value, FlValue* key, FlValue* child_value);
 
 /**
  * fl_value_set_string:
- * @value: an #FlValue of type #FL_VALUE_TYPE_MAP
- * @key: a UTF-8 text key
- * @child_value: an #FlValue
+ * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
+ * @key: a UTF-8 text key.
+ * @child_value: an #FlValue.
  *
  * Sets a value in the map with a text key. If an existing value was in the map
  * with the same key it is replaced. Calling this with an #FlValue that is not
@@ -315,9 +374,9 @@ void fl_value_set_string(FlValue* value,
 
 /**
  * fl_value_set_string_take:
- * @value: an #FlValue of type #FL_VALUE_TYPE_MAP
- * @key: a UTF-8 text key
- * @child_value: (transfer full): an #FlValue
+ * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
+ * @key: a UTF-8 text key.
+ * @child_value: (transfer full): an #FlValue.
  *
  * Sets a value in the map with a text key, taking ownership of the value. If an
  * existing value was in the map with the same key it is replaced. Calling this
@@ -330,7 +389,7 @@ void fl_value_set_string_take(FlValue* value,
 
 /**
  * fl_value_get_bool:
- * @value: an #FlValue of type #FL_VALUE_TYPE_BOOL
+ * @value: an #FlValue of type #FL_VALUE_TYPE_BOOL.
  *
  * Gets the boolean value of @value. Calling this with an #FlValue that is
  * not of type #FL_VALUE_TYPE_BOOL is a programming error.
@@ -341,7 +400,7 @@ bool fl_value_get_bool(FlValue* value);
 
 /**
  * fl_value_get_int:
- * @value: an #FlValue of type #FL_VALUE_TYPE_INT
+ * @value: an #FlValue of type #FL_VALUE_TYPE_INT.
  *
  * Gets the integer number of @value. Calling this with an #FlValue that is
  * not of type #FL_VALUE_TYPE_INT is a programming error.
@@ -352,7 +411,7 @@ int64_t fl_value_get_int(FlValue* value);
 
 /**
  * fl_value_get_double:
- * @value: an #FlValue of type #FL_VALUE_TYPE_FLOAT
+ * @value: an #FlValue of type #FL_VALUE_TYPE_FLOAT.
  *
  * Gets the floating point number of @value. Calling this with an #FlValue
  * that is not of type #FL_VALUE_TYPE_FLOAT is a programming error.
@@ -363,7 +422,7 @@ double fl_value_get_float(FlValue* value);
 
 /**
  * fl_value_get_string:
- * @value: an #FlValue of type #FL_VALUE_TYPE_STRING
+ * @value: an #FlValue of type #FL_VALUE_TYPE_STRING.
  *
  * Gets the UTF-8 text contained in @value. Calling this with an #FlValue
  * that is not of type #FL_VALUE_TYPE_STRING is a programming error.
@@ -387,7 +446,7 @@ size_t fl_value_get_length(FlValue* value);
 
 /**
  * fl_value_get_uint8_list:
- * @value: an #FlValue of type #FL_VALUE_TYPE_UINT8_LIST
+ * @value: an #FlValue of type #FL_VALUE_TYPE_UINT8_LIST.
  *
  * Gets the array of unisigned 8 bit integers @value contains. The data
  * contains fl_get_length() elements. Calling this with an #FlValue that is
@@ -399,7 +458,7 @@ const uint8_t* fl_value_get_uint8_list(FlValue* value);
 
 /**
  * fl_value_get_int32_list:
- * @value: an #FlValue of type #FL_VALUE_TYPE_INT32_LIST
+ * @value: an #FlValue of type #FL_VALUE_TYPE_INT32_LIST.
  *
  * Gets the array of 32 bit integers @value contains. The data contains
  * fl_get_length() elements. Calling this with an #FlValue that is not of
@@ -411,7 +470,7 @@ const int32_t* fl_value_get_int32_list(FlValue* value);
 
 /**
  * fl_value_get_int64_list:
- * @value: an #FlValue of type #FL_VALUE_TYPE_INT64_LIST
+ * @value: an #FlValue of type #FL_VALUE_TYPE_INT64_LIST.
  *
  * Gets the array of 64 bit integers @value contains. The data contains
  * fl_get_length() elements. Calling this with an #FlValue that is not of
@@ -423,7 +482,7 @@ const int64_t* fl_value_get_int64_list(FlValue* value);
 
 /**
  * fl_value_get_float_list:
- * @value: an #FlValue of type #FL_VALUE_TYPE_FLOAT_LIST
+ * @value: an #FlValue of type #FL_VALUE_TYPE_FLOAT_LIST.
  *
  * Gets the array of floating point numbers @value contains. The data
  * contains fl_get_length() elements. Calling this with an #FlValue that is
@@ -440,9 +499,10 @@ const double* fl_value_get_float_list(FlValue* value);
  *
  * Gets a child element of the list. It is a programming error to request an
  * index that is outside the size of the list as returned from
- * fl_value_get_length().
+ * fl_value_get_length(). Calling this with an #FlValue that is not of type
+ * #FL_VALUE_TYPE_LIST is a programming error.
  *
- * Returns: an #FlValue
+ * Returns: an #FlValue.
  */
 FlValue* fl_value_get_list_value(FlValue* value, size_t index);
 
@@ -453,8 +513,10 @@ FlValue* fl_value_get_list_value(FlValue* value, size_t index);
  *
  * Gets an key from the map. It is a programming error to request an index that
  * is outside the size of the list as returned from fl_value_get_length().
+ * Calling this with an #FlValue that is not of type #FL_VALUE_TYPE_MAP is a
+ * programming error.
  *
- * Returns: an #FlValue
+ * Returns: an #FlValue.
  */
 FlValue* fl_value_get_map_key(FlValue* value, size_t index);
 
@@ -465,18 +527,21 @@ FlValue* fl_value_get_map_key(FlValue* value, size_t index);
  *
  * Gets a value from the map. It is a programming error to request an index that
  * is outside the size of the list as returned from fl_value_get_length().
+ * Calling this with an #FlValue that is not of type #FL_VALUE_TYPE_MAP is a
+ * programming error.
  *
- * Returns: an #FlValue
+ * Returns: an #FlValue.
  */
 FlValue* fl_value_get_map_value(FlValue* value, size_t index);
 
 /**
  * fl_value_lookup:
- * @value: an #FlValue of type #FL_VALUE_TYPE_MAP
- * @key: a key value
+ * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
+ * @key: a key value.
  *
  * Gets the map entry that matches @key. Keys are checked using
- * fl_value_equal().
+ * fl_value_equal(). Calling this with an #FlValue that is not of type
+ * #FL_VALUE_TYPE_MAP is a programming error.
  *
  * Map lookups are not optimised for performance - if have a large map or need
  * frequent access you should copy the data into another structure, e.g.
@@ -488,11 +553,12 @@ FlValue* fl_value_lookup(FlValue* value, FlValue* key);
 
 /**
  * fl_value_lookup_string:
- * @value: an #FlValue of type #FL_VALUE_TYPE_MAP
- * @key: a key value
+ * @value: an #FlValue of type #FL_VALUE_TYPE_MAP.
+ * @key: a key value.
  *
  * Gets the map entry that matches @key. Keys are checked using
- * fl_value_equal().
+ * fl_value_equal(). Calling this with an #FlValue that is not of type
+ * #FL_VALUE_TYPE_MAP is a programming error.
  *
  * Map lookups are not optimised for performance - if have a large map or need
  * frequent access you should copy the data into another structure, e.g.
diff --git a/shell/platform/linux/public/flutter_linux/fl_view.h b/shell/platform/linux/public/flutter_linux/fl_view.h
index d939ab039..1b240e5a4 100644
--- a/shell/platform/linux/public/flutter_linux/fl_view.h
+++ b/shell/platform/linux/public/flutter_linux/fl_view.h
@@ -22,6 +22,18 @@ G_DECLARE_FINAL_TYPE(FlView, fl_view, FL, VIEW, GtkWidget)
  * FlView:
  *
  * #FlView is a GTK widget that is capable of displaying a Flutter application.
+ *
+ * The following example shows how to set up a view in a GTK application:
+ * |[<!-- language="C" -->
+ *   FlDartProject *project = fl_dart_project_new ("data");
+ *   FlView *view = fl_view_new (project);
+ *   gtk_widget_show (GTK_WIDGET (view));
+ *   gtk_container_add (GTK_CONTAINER (parent), view);
+ *
+ *   FlBinaryMessenger *mesenger =
+ *     fl_engine_get_binary_messenger (fl_view_get_engine (view));
+ *   setup_channels_or_plugins (messenger);
+ * ]|
  */
 
 /**
@@ -30,17 +42,17 @@ G_DECLARE_FINAL_TYPE(FlView, fl_view, FL, VIEW, GtkWidget)
  *
  * Creates a widget to show Flutter application.
  *
- * Returns: a new #FlView
+ * Returns: a new #FlView.
  */
 FlView* fl_view_new(FlDartProject* project);
 
 /**
  * fl_view_get_engine:
- * @view: a #FlView
+ * @view: an #FlView.
  *
  * Gets the engine being rendered in the view.
  *
- * Returns: a #FlEngine
+ * Returns: an #FlEngine.
  */
 FlEngine* fl_view_get_engine(FlView* view);
 
-- 
GitLab