Update comments for grammar and content to required style (#18491)
diff --git a/shell/platform/linux/fl_binary_codec_test.cc b/shell/platform/linux/fl_binary_codec_test.cc
index 5405e8a..76f8b24 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 @@
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 @@
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 88212c1..ce70c51 100644
--- a/shell/platform/linux/fl_binary_messenger_private.h
+++ b/shell/platform/linux/fl_binary_messenger_private.h
@@ -15,7 +15,8 @@
* 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 da91a16..1007cfe 100644
--- a/shell/platform/linux/fl_engine_private.h
+++ b/shell/platform/linux/fl_engine_private.h
@@ -27,11 +27,11 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 587e960..58063f3 100644
--- a/shell/platform/linux/fl_renderer.h
+++ b/shell/platform/linux/fl_renderer.h
@@ -35,8 +35,11 @@
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 @@
/**
* 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 ca36341..14b19e5 100644
--- a/shell/platform/linux/fl_renderer_x11.h
+++ b/shell/platform/linux/fl_renderer_x11.h
@@ -20,25 +20,25 @@
/**
* 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 c14ec95..82cebef 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 f435895..625736c 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 @@
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 @@
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 49aa6d8..1c5bdbe 100644
--- a/shell/platform/linux/fl_view.cc
+++ b/shell/platform/linux/fl_view.cc
@@ -15,9 +15,16 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 5bdd5bb..d5a9669 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 @@
* #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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 00e727d..e7223d8 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 @@
* 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 @@
/**
* 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 a144471..c29e978 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 @@
* FlBinaryMessenger:
*
* #FlBinaryMessenger is an object that allows sending and receiving of platform
- * messages with a #FlEngine.
+ * messages with an #FlEngine.
*/
/**
@@ -36,11 +36,11 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 970618c..e82f6ac 100644
--- a/shell/platform/linux/public/flutter_linux/fl_dart_project.h
+++ b/shell/platform/linux/public/flutter_linux/fl_dart_project.h
@@ -19,27 +19,12 @@
* 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"
- *
- * Create 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)
- *
- * The path can either be absolute, or relative to the directory containing the
- * running executable.
- *
- * Returns: a new #FlDartProject
- */
-
-/**
- * fl_dart_project_new:
- * @path: a file path, e.g. "my_dart_project"
+ * @path: a file path, e.g. "my_dart_project".
*
* Creates a Flutter project. The project path should contain the following
* top-level items:
@@ -49,40 +34,55 @@
* 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: (type filename): a file path, e.g. "my_dart_project".
+ *
+ * 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)
+ *
+ * The path can either be absolute, or relative to the directory containing the
+ * running executable.
+ *
+ * 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 9473717..6299722 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 @@
/**
* 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 5796ffe..ddf6818 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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 03e17db..b74aad2 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 5ba56ce..2af7b83 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 @@
* 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 @@
/*
* 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 8778046..8f49e9f 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 @@
* 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 @@
/**
* 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 f624bad..4f0ffd3 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 @@
* 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 @@
* - #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 @@
/**
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* @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 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
/**
* fl_value_ref:
- * @value: an #FlValue
+ * @value: an #FlValue.
*
* Increases the reference count of an #FlValue.
*
@@ -221,8 +280,8 @@
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 @@
/**
* fl_value_get_type:
- * @value: an #FlValue
+ * @value: an #FlValue.
*
* Gets the type of @value.
*
@@ -241,8 +300,8 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
*
* 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 @@
*
* 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 @@
*
* 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 @@
/**
* 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 d939ab0..1b240e5 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 @@
* 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 @@
*
* 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);
