Merge branch 'bilelmoussaoui/docs' into 'main'

docs: Document most of the public APIs

See merge request chergert/libmks!18

README.md

@@ -1,7 +1,7 @@
 # libmks
 
-This library provides a "Mouse, Keyboard, and Screen" to Qemu using the
+This library provides a "Mouse, Keyboard, and Screen" to QEMU using the
-D-Bus device support in Qemu and GTK 4.
+D-Bus device support in QEMU and GTK 4.
 
 # Documentation
 
@@ -9,9 +9,9 @@ Nightly documentation can be found [here](https://chergert.pages.gitlab.gnome.or
 
 # Testing
 
-By default, Qemu will connect to your user session D-Bus if you do not
+By default, QEMU will connect to your user session D-Bus if you do not
 provide an address for `-display dbus`. Therefore, it is pretty easy to
-test things by running Qemu manually and then connecting with the test
+test things by running QEMU manually and then connecting with the test
 program `./tools/mks`.
 
 ```sh

docs/Mks.toml.in

@@ -6,7 +6,7 @@ website_url = "https://gitlab.gnome.org/chergert/libmks"
 docs_url = "https://chergert.pages.gitlab.gnome.org/libmks/"
 authors = "Christian Hergert"
 license = "LGPL-2.1-or-later"
-description = "Mouse, Keyboard, and Screen to Qemu"
+description = "Mouse, Keyboard, and Screen to QEMU"
 dependencies = [ "GObject-2.0", "Gdk-4.0", "Gtk-4.0" ]
 devhelp = true
 search_index = true

lib/meson.build

@@ -138,7 +138,7 @@ libmks_dep = declare_dependency(
 install_headers(libmks_headers, subdir: 'libmks-@0@'.format(api_version))
 
 pkg.generate(
-  description: 'A shared library for Mouse, Keyboard, and Screen to Qemu',
+  description: 'A shared library for Mouse, Keyboard, and Screen to QEMU',
     libraries: libmks,
          name: 'libmks',
      filebase: 'libmks-' + api_version,

lib/mks-device.c

@@ -23,6 +23,12 @@
 
 #include "mks-device-private.h"
 
+/**
+ * MksDevice:
+ * 
+ * An abstraction of a virtualized QEMU device.
+ */
+
 G_DEFINE_TYPE (MksDevice, mks_device, G_TYPE_OBJECT)
 
 enum {
@@ -84,6 +90,11 @@ mks_device_class_init (MksDeviceClass *klass)
 
   klass->setup = mks_device_real_setup;
 
+  /**
+   * MksDevice:name:
+   * 
+   * The device name.
+  */
   properties [PROP_NAME] =
     g_param_spec_string ("name", NULL, NULL,
                          NULL,
@@ -97,6 +108,12 @@ mks_device_init (MksDevice *self)
 {
 }
 
+/**
+ * mks_device_get_name:
+ * @self: A `MksDevice`
+ * 
+ * Gets the device name. 
+ */
 const char *
 mks_device_get_name (MksDevice *self)
 {

lib/mks-display-picture.c

@@ -347,7 +347,7 @@ mks_display_picture_legacy_event_cb (MksDisplayPicture        *self,
 
               /*
                * Currently there is no touchpad D-Bus interface to communicate
-               * with Qemu. That is something we would very much want to have
+               * with QEMU. That is something we would very much want to have
                * in the future so that we can do this properly.
                *
                * For now, we just "emulate" scroll events by looking at direction

lib/mks-init.c

@@ -41,7 +41,7 @@ mks_init_gtypes (void)
 {
   g_resources_register (mks_get_resource ());
 
-  /* First register GTypes for Qemu IPC */
+  /* First register GTypes for QEMU IPC */
   g_type_ensure (MKS_QEMU_TYPE_AUDIO);
   g_type_ensure (MKS_QEMU_TYPE_AUDIO_IN_LISTENER);
   g_type_ensure (MKS_QEMU_TYPE_AUDIO_OUT_LISTENER);
@@ -66,6 +66,13 @@ mks_init_gtypes (void)
   g_type_ensure (MKS_TYPE_SESSION);
 }
 
+/**
+ * mks_init:
+ *
+ * Initializes the library.
+ * 
+ * The function must be called before using any of the library functions.
+ */
 void
 mks_init (void)
 {
@@ -86,18 +93,33 @@ _mks_init (void)
   mks_init ();
 }
 
+/**
+ * mks_get_major_version:
+ * 
+ * The major version the library.
+ */
 int
 mks_get_major_version (void)
 {
   return MKS_MAJOR_VERSION;
 }
 
+/**
+ * mks_get_minor_version:
+ * 
+ * The minor version the library.
+ */
 int
 mks_get_minor_version (void)
 {
   return MKS_MINOR_VERSION;
 }
 
+/**
+ * mks_get_micro_version:
+ * 
+ * The micro version the library.
+ */
 int
 mks_get_micro_version (void)
 {

lib/mks-keyboard.c

@@ -29,6 +29,12 @@
 
 #include "mks-keymap-xorgevdev2qnum-private.h"
 
+/**
+ * MksKeyboard:
+ * 
+ * A virtualized QEMU keyboard.
+ */
+
 struct _MksKeyboard
 {
   MksDevice        parent_instance;
@@ -152,6 +158,11 @@ mks_keyboard_class_init (MksKeyboardClass *klass)
   object_class->dispose = mks_keyboard_dispose;
   object_class->get_property = mks_keyboard_get_property;
 
+  /**
+   * MksKeyboard:modifiers:
+   * 
+   * Active keyboard modifiers.
+   */
   properties [PROP_MODIFIERS] =
     g_param_spec_flags ("modifiers", NULL, NULL,
                         MKS_TYPE_KEYBOARD_MODIFIER,
@@ -166,6 +177,12 @@ mks_keyboard_init (MksKeyboard *self)
 {
 }
 
+/**
+ * mks_keyboard_get_modifiers:
+ * @self: an #MksKeyboard
+ * 
+ * Get the active keyboard modifiers.
+ */
 MksKeyboardModifier
 mks_keyboard_get_modifiers (MksKeyboard *self)
 {
@@ -221,7 +238,7 @@ mks_keyboard_press_cb (GObject      *object,
  * @callback: a #GAsyncReadyCallback to execute upon completion
  * @user_data: closure data for @callback
  *
- * Asynchronously presses @keycode.
+ * Presses @keycode.
  */
 void
 mks_keyboard_press (MksKeyboard         *self,
@@ -253,6 +270,17 @@ mks_keyboard_press (MksKeyboard         *self,
   MKS_EXIT;
 }
 
+/**
+ * mks_keyboard_press_finish:
+ * @self: a `MksKeyboard`
+ * @result: a #GAsyncResult provided to callback
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes a call to [method@Mks.Keyboard.press].
+ *
+ * Returns: %TRUE if the operation completed successfully; otherwise %FALSE
+ *   and @error is set.
+ */
 gboolean
 mks_keyboard_press_finish (MksKeyboard   *self,
                            GAsyncResult  *result,
@@ -270,6 +298,19 @@ mks_keyboard_press_finish (MksKeyboard   *self,
   MKS_RETURN (ret);
 }
 
+
+/**
+ * mks_keyboard_press_sync:
+ * @self: an #MksKeyboard
+ * @keycode: the hardware keycode
+ * @cancellable: (nullable): a #GCancellable
+ * @error: a location for a #GError, or %NULL
+ *
+ * Synchronously press the `keycode`.
+ *
+ * Returns: %TRUE if the operation was acknowledged by the QEMU instance;
+ *   otherwise %FALSE and @error is set.
+ */
 gboolean
 mks_keyboard_press_sync (MksKeyboard   *self,
                          guint          keycode,
@@ -322,7 +363,7 @@ mks_keyboard_release_cb (GObject      *object,
  * @callback: a #GAsyncReadyCallback to execute upon completion
  * @user_data: closure data for @callback
  *
- * Asynchronously releases @keycode.
+ * Releases @keycode.
  */
 void
 mks_keyboard_release (MksKeyboard         *self,
@@ -354,6 +395,17 @@ mks_keyboard_release (MksKeyboard         *self,
   MKS_EXIT;
 }
 
+/**
+ * mks_keyboard_release_finish:
+ * @self: a `MksKeyboard`
+ * @result: a #GAsyncResult provided to callback
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes a call to [method@Mks.Keyboard.release].
+ *
+ * Returns: %TRUE if the operation completed successfully; otherwise %FALSE
+ *   and @error is set.
+ */
 gboolean
 mks_keyboard_release_finish (MksKeyboard   *self,
                              GAsyncResult  *result,
@@ -371,6 +423,18 @@ mks_keyboard_release_finish (MksKeyboard   *self,
   MKS_RETURN (ret);
 }
 
+/**
+ * mks_keyboard_release_sync:
+ * @self: an #MksKeyboard
+ * @keycode: the hardware keycode
+ * @cancellable: (nullable): a #GCancellable
+ * @error: a location for a #GError, or %NULL
+ *
+ * Synchronously release the `keycode`.
+ *
+ * Returns: %TRUE if the operation was acknowledged by the QEMU instance;
+ *   otherwise %FALSE and @error is set.
+ */
 gboolean
 mks_keyboard_release_sync (MksKeyboard   *self,
                            guint          keycode,

lib/mks-keyboard.h

@@ -42,6 +42,15 @@ G_BEGIN_DECLS
 
 typedef struct _MksKeyboardClass MksKeyboardClass;
 
+/**
+ * MksKeyboardModifier:
+ * @MKS_KEYBOARD_MODIFIER_NONE: No modifier.
+ * @MKS_KEYBOARD_MODIFIER_SCROLL_LOCK: Scroll lock.
+ * @MKS_KEYBOARD_MODIFIER_NUM_LOCK: Numeric lock.
+ * @MKS_KEYBOARD_MODIFIER_CAPS_LOCK: Caps lock.
+ * 
+ * The active keyboard modifiers.
+ */
 typedef enum _MksKeyboardModifier
 {
   MKS_KEYBOARD_MODIFIER_NONE        = 0,

lib/mks-mouse.c

@@ -25,6 +25,12 @@
 #include "mks-mouse.h"
 #include "mks-util-private.h"
 
+/**
+ * MksMouse:
+ * 
+ * A virtualized QEMU mouse.
+ */
+
 struct _MksMouse
 {
   MksDevice parent_instance;
@@ -121,6 +127,11 @@ mks_mouse_class_init (MksMouseClass *klass)
 
   device_class->setup = mks_mouse_setup;
 
+  /**
+   * MksMouse:is-absolute:
+   * 
+   * Whether the mouse is using absolute movements.
+   */
   properties [PROP_IS_ABSOLUTE] =
     g_param_spec_boolean ("is-absolute", NULL, NULL,
                           FALSE,
@@ -134,6 +145,12 @@ mks_mouse_init (MksMouse *self)
 {
 }
 
+/**
+ * mks_mouse_get_is_absolute:
+ * @self: A `MksMouse`.
+ * 
+ * Whether the mouse is using absolute movements.
+ */
 gboolean
 mks_mouse_get_is_absolute (MksMouse *self)
 {
@@ -224,6 +241,17 @@ mks_mouse_press (MksMouse            *self,
   MKS_EXIT;
 }
 
+/**
+ * mks_mouse_press_finish:
+ * @self: a `MksMouse`
+ * @result: a #GAsyncResult provided to callback
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes a call to [method@Mks.Mouse.press].
+ *
+ * Returns: %TRUE if the operation completed successfully; otherwise %FALSE
+ *   and @error is set.
+ */
 gboolean
 mks_mouse_press_finish (MksMouse      *self,
                         GAsyncResult  *result,
@@ -241,6 +269,18 @@ mks_mouse_press_finish (MksMouse      *self,
   MKS_RETURN (ret);
 }
 
+/**
+ * mks_mouse_press_sync:
+ * @self: an #MksMouse
+ * @button: the #MksMouseButton that was released
+ * @cancellable: (nullable): a #GCancellable
+ * @error: a location for a #GError, or %NULL
+ *
+ * Synchronously press a mouse button.
+ *
+ * Returns: %TRUE if the operation was acknowledged by the QEMU instance;
+ *   otherwise %FALSE and @error is set.
+ */
 gboolean
 mks_mouse_press_sync (MksMouse        *self,
                       MksMouseButton   button,
@@ -288,7 +328,7 @@ mks_mouse_release_cb (GObject      *object,
 /**
  * mks_mouse_release:
  * @self: an #MksMouse
- * @button: the #MksMouseButton that was releaseed
+ * @button: the #MksMouseButton that was released
  * @cancellable: (nullable): a #GCancellable
  * @callback: a #GAsyncReadyCallback to execute upon completion
  * @user_data: closure data for @callback
@@ -325,6 +365,17 @@ mks_mouse_release (MksMouse            *self,
   MKS_EXIT;
 }
 
+/**
+ * mks_mouse_release_finish:
+ * @self: a `MksMouse`
+ * @result: a #GAsyncResult provided to callback
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes a call to [method@Mks.Mouse.release].
+ *
+ * Returns: %TRUE if the operation completed successfully; otherwise %FALSE
+ *   and @error is set.
+ */
 gboolean
 mks_mouse_release_finish (MksMouse      *self,
                           GAsyncResult  *result,
@@ -342,6 +393,18 @@ mks_mouse_release_finish (MksMouse      *self,
   MKS_RETURN (ret);
 }
 
+/**
+ * mks_mouse_release_sync:
+ * @self: an #MksMouse
+ * @button: the #MksMouseButton that was released
+ * @cancellable: (nullable): a #GCancellable
+ * @error: a location for a #GError, or %NULL
+ *
+ * Synchronously releases a mouse button.
+ *
+ * Returns: %TRUE if the operation was acknowledged by the QEMU instance;
+ *   otherwise %FALSE and @error is set.
+ */
 gboolean
 mks_mouse_release_sync (MksMouse        *self,
                         MksMouseButton   button,
@@ -431,6 +494,17 @@ mks_mouse_move_to (MksMouse            *self,
   MKS_EXIT;
 }
 
+/**
+ * mks_mouse_move_to_finish:
+ * @self: a `MksMouse`
+ * @result: a #GAsyncResult provided to callback
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes a call to [method@Mks.Mouse.move_to].
+ *
+ * Returns: %TRUE if the operation completed successfully; otherwise %FALSE
+ *   and @error is set.
+ */
 gboolean
 mks_mouse_move_to_finish (MksMouse      *self,
                           GAsyncResult  *result,
@@ -456,9 +530,9 @@ mks_mouse_move_to_finish (MksMouse      *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: a location for a #GError, or %NULL
  *
- * Moves to the absolute position at coordinates (x,y).
+ * Synchronously moves to the absolute position at coordinates (x,y).
  *
- * Returns: %TRUE if the operation was acknowledged by the Qemu instance;
+ * Returns: %TRUE if the operation was acknowledged by the QEMU instance;
  *   otherwise %FALSE and @error is set.
  */
 gboolean
@@ -554,6 +628,17 @@ mks_mouse_move_by (MksMouse            *self,
   MKS_EXIT;
 }
 
+/**
+ * mks_mouse_move_by_finish:
+ * @self: a `MksMouse`
+ * @result: a #GAsyncResult provided to callback
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes a call to [method@Mks.Mouse.move_by].
+ *
+ * Returns: %TRUE if the operation completed successfully; otherwise %FALSE
+ *   and @error is set.
+ */
 gboolean
 mks_mouse_move_by_finish (MksMouse      *self,
                           GAsyncResult  *result,
@@ -579,9 +664,9 @@ mks_mouse_move_by_finish (MksMouse      *self,
  * @cancellable: (nullable): a #GCancellable
  * @error: a location for a #GError, or %NULL
  *
- * Moves the mouse by delta_x and delta_y.
+ * Synchronously moves the mouse by delta_x and delta_y.
  *
- * Returns: %TRUE if the operation was acknowledged by the Qemu instance;
+ * Returns: %TRUE if the operation was acknowledged by the QEMU instance;
  *   otherwise %FALSE and @error is set.
  */
 gboolean

lib/mks-mouse.h

@@ -42,6 +42,18 @@ G_BEGIN_DECLS
 
 typedef struct _MksMouseClass MksMouseClass;
 
+/**
+ * MksMouseButton:
+ * @MKS_MOUSE_BUTTON_LEFT: Left button.
+ * @MKS_MOUSE_BUTTON_MIDDLE: Middle button.
+ * @MKS_MOUSE_BUTTON_RIGHT: Right button.
+ * @MKS_MOUSE_BUTTON_WHEEL_UP: Wheel-up button.
+ * @MKS_MOUSE_BUTTON_WHEEL_DOWN: Wheel-down button.
+ * @MKS_MOUSE_BUTTON_SIDE: Side button.
+ * @MKS_MOUSE_BUTTON_EXTRA: Extra button.
+ * 
+ * A mouse button.
+ */
 typedef enum _MksMouseButton
 {
   MKS_MOUSE_BUTTON_LEFT       = 0,

lib/mks-paintable.c

@@ -820,7 +820,7 @@ _mks_paintable_new (GCancellable  *cancellable,
  * _mks_paintable_get_cursor:
  * @self: a #MksPaintable
  *
- * Gets the cursor as defined by the Qemu instance.
+ * Gets the cursor as defined by the QEMU instance.
  *
  * Returns: (transfer none) (nullable): a #GdkCursor or %NULL
  */

lib/mks-screen-attributes.c

@@ -23,6 +23,15 @@
 
 #include "mks-screen-attributes-private.h"
 
+/**
+ * MksScreenAttributes:
+ * 
+ * Screen attributes.
+ * 
+ * The attributes are used to reconfigure the QEMU instance with
+ * [method@Mks.Screen.configure] or [method@Mks.Screen.configure_sync].
+ */
+
 G_DEFINE_BOXED_TYPE (MksScreenAttributes,
                      mks_screen_attributes,
                      mks_screen_attributes_copy,
@@ -63,8 +72,10 @@ mks_screen_attributes_copy (MksScreenAttributes *self)
  * mks_screen_attributes_free:
  * @self: a #MksScreenAttributes
  *
- * Frees a #MksScreenAttributes allocated using mks_screen_attributes_new()
+ * Frees a #MksScreenAttributes.
- * or mks_screen_attributes_copy().
+ * 
+ * Allocated using [ctor@Mks.ScreenAttributes.new]
+ * or [method@Mks.ScreenAttributes.copy].
  */
 void
 mks_screen_attributes_free (MksScreenAttributes *self)
@@ -94,6 +105,13 @@ mks_screen_attributes_equal (MksScreenAttributes *self,
           self->height_mm == other->height_mm);
 }
 
+/**
+ * mks_screen_attributes_set_width_mm:
+ * @self: A MksScreenAttributes.
+ * @width_mm: The screen width. 
+ * 
+ * Set the screen width in millimeters.
+ */
 void
 mks_screen_attributes_set_width_mm (MksScreenAttributes *self,
                                     guint16              width_mm)
@@ -101,6 +119,13 @@ mks_screen_attributes_set_width_mm (MksScreenAttributes *self,
   self->width_mm = width_mm;
 }
 
+/**
+ * mks_screen_attributes_set_height_mm:
+ * @self: A MksScreenAttributes.
+ * @height_mm: The screen height. 
+ * 
+ * Set the screen height in millimeters.
+ */
 void
 mks_screen_attributes_set_height_mm (MksScreenAttributes *self,
                                      guint16              height_mm)
@@ -108,6 +133,13 @@ mks_screen_attributes_set_height_mm (MksScreenAttributes *self,
   self->height_mm = height_mm;
 }
 
+/**
+ * mks_screen_attributes_set_x_offset:
+ * @self: A MksScreenAttributes.
+ * @x_offset: The screen's horizontal offset. 
+ * 
+ * Set the screen's horizontal offset in pixels.
+ */
 void
 mks_screen_attributes_set_x_offset (MksScreenAttributes *self,
                                     int                  x_offset)
@@ -115,6 +147,13 @@ mks_screen_attributes_set_x_offset (MksScreenAttributes *self,
   self->x_offset = x_offset;
 }
 
+/**
+ * mks_screen_attributes_set_y_offset:
+ * @self: A MksScreenAttributes.
+ * @y_offset: The screen's vertical offset. 
+ * 
+ * Set the screen's vertical offset in pixels.
+ */
 void
 mks_screen_attributes_set_y_offset (MksScreenAttributes *self,
                                     int                  y_offset)
@@ -122,6 +161,13 @@ mks_screen_attributes_set_y_offset (MksScreenAttributes *self,
   self->y_offset = y_offset;
 }
 
+/**
+ * mks_screen_attributes_set_width:
+ * @self: A MksScreenAttributes.
+ * @width: The screen width. 
+ * 
+ * Set the screen width in pixels.
+ */
 void
 mks_screen_attributes_set_width (MksScreenAttributes *self,
                                  guint                width)
@@ -129,6 +175,13 @@ mks_screen_attributes_set_width (MksScreenAttributes *self,
   self->width = width;
 }
 
+/**
+ * mks_screen_attributes_set_height:
+ * @self: A MksScreenAttributes.
+ * @height: The screen height. 
+ * 
+ * Set the screen height in pixels.
+ */
 void
 mks_screen_attributes_set_height (MksScreenAttributes *self,
                                   guint                height)

lib/mks-screen.c

@@ -478,11 +478,11 @@ mks_screen_configure_cb (GObject      *object,
  * @callback: a #GAsyncReadyCallback to execute upon completion
  * @user_data: closure data for @callback
  *
- * Requests the Qemu instance reconfigure the screen with @attributes.
+ * Requests the QEMU instance reconfigure the screen with @attributes.
  *
  * This function takes ownership of @attributes.
  *
- * @callback is executed upon acknowledgment from the Qemu instance or
+ * @callback is executed upon acknowledgment from the QEMU instance or
  * if the request timed out.
  *
  * Call mks_screen_configure_finish() to get the result.
@@ -550,7 +550,7 @@ mks_screen_configure_finish (MksScreen     *self,
  * @cancellable: a #GCancellable
  * @error: a location for a #GError, or %NULL
  *
- * Requests the Qemu instance reconfigure the screen using @attributes.
+ * Requests the QEMU instance reconfigure the screen using @attributes.
  *
  * This function takes ownership of @attributes.
  *
@@ -613,7 +613,7 @@ mks_screen_attach_cb (GObject      *object,
  * contents of the screen.
  *
  * This function registers a new `socketpair()` which is shared with
- * the Qemu instance to receive rendering updates. Those updates are
+ * the QEMU instance to receive rendering updates. Those updates are
  * propagated to the resulting #GdkPainable which can be retrieved
  * using mks_screen_attach_finish() from @callback.
  */
@@ -661,11 +661,11 @@ failure:
  * @result: a #GAsyncResult provided to callback
  * @error: a location for a #GError, or %NULL
  *
- * Completes an asynchronous request to create a #GdkPaintable containing
+ * Completes an asynchronous request to create a [iface@Gdk.Paintable] containing
- * the contents of #MksScreen in the Qemu instance.
+ * the contents of #MksScreen in the QEMU instance.
  *
- * The resulting #GdkPaintable will be updated as changes are delivered
+ * The resulting [iface@Gdk.Paintable] will be updated as changes are delivered
- * from Qemu over a private `socketpair()`. In the typical case, those
+ * from QEMU over a private `socketpair()`. In the typical case, those
  * changes are propagated using a DMA-BUF and damage notifications.
  *
  * Returns: (transfer full): a #GdkPainable if successful; otherwise %NULL
@@ -689,7 +689,7 @@ mks_screen_attach_finish (MksScreen     *self,
  * @error: (nullable): a location for a #GError, or %NULL
  *
  * Synchronous request to attach to screen, creating a paintable that can
- * be used to update display as the Qemu instance updates.
+ * be used to update display as the QEMU instance updates.
  *
  * Returns: (transfer full): a #GdkPaintable if successful; otherwise %NULL
  *   and @error is set.

lib/mks-screen.h

@@ -43,6 +43,13 @@ G_BEGIN_DECLS
 
 typedef struct _MksScreenClass MksScreenClass;
 
+/**
+ * MksScreenKind:
+ * @MKS_SCREEN_KIND_TEXT: A text only screen.
+ * @MKS_SCREEN_KIND_GRAPHIC: A graphical screen.
+ * 
+ * A screen kind.
+ */
 typedef enum _MksScreenKind
 {
   MKS_SCREEN_KIND_TEXT = 0,

lib/mks-session.c

@@ -28,32 +28,32 @@
 #include "mks-session.h"
 
 /**
- * SECTION:mks-session
+ * MksSession:
- * @Title: MksSession
+ * 
- * @Short_description: Session connected to a Qemu VM
+ * Session connected to a QEMU VM
  *
- * The #MksSession represents a connection to a Qemu VM instance. It contains
+ * The `MksSession` represents a connection to a QEMU VM instance. It contains
  * devices such as the mouse, keyboard, and screen which can be used with GTK.
  *
- * You may monitor #MksSession:devices using #GListModel:items-changed to be
+ * You may monitor [property@Mks.Session:devices] using [signal@Gio.ListModel::items-changed] to be
  * notified of changes to available devices in the session.
  *
- * # Connecting To Qemu
+ * # Connecting To QEMU
  *
- * To use #MksSession, you should create your Qemu instance using `dbus` for
+ * To use `MksSession`, you should create your QEMU instance using `dbus` for
  * the various devices that support it. You'll need to provide your P2P D-Bus
- * address when connecting to Qemu.
+ * address when connecting to QEMU.
  *
- * Using the same #GDBusConnection, create a #MksSession with
+ * Using the same [class@Gio.DBusConnection], create a `MksSession` with
- * mks_session_new_for_connection(). The #MksSession instance will negotiate
+ * [func@Mks.Session.new_for_connection]. The `MksSession` instance will negotiate
  * with the peer to determine what devices are available and expose them
- * via the #MksSession:devices #GListModel.
+ * via the [property@Mks.Session:devices] [iface@Gio.ListModel].
  *
  * # Creating Widgets
  *
- * You can create a new widget to embed in your application by waiting for
+ * You can create a new widget to embed in your application by calling
- * a #MksScreen to become available in the list model or connecting to the
+ * [method@Mks.Session.ref_screen] and set the screen for the [class@Mks.Display]
- * #GObject::notify signal for the #MksSession:screen property.
+ * with [method@Mks.Display.set_screen].
  */
 
 static gboolean mks_session_initable_init              (GInitable            *initable,
@@ -72,15 +72,15 @@ struct _MksSession
 {
   GObject parent_instance;
 
-  /* @connection is used to communicate with the Qemu instance. It is expected
+  /* @connection is used to communicate with the QEMU instance. It is expected
    * to be a private point-to-point connection over a Unix socket, socketpair(),
    * or other channel capable of passing FDs between peers.
    */
   GDBusConnection *connection;
 
-  /* As devices are discovered from the Qemu instance, MksDevice-based objects
+  /* As devices are discovered from the QEMU instance, MksDevice-based objects
    * are created for them and stored in @devices. Applications will work with
-   * these objects to perform operations on the Qemu instance. When we discover
+   * these objects to perform operations on the QEMU instance. When we discover
    * the devices have been removed, we drop them from the listmodel.
    */
   GListStore *devices;
@@ -93,7 +93,7 @@ struct _MksSession
   GListModel *devices_read_only;
 
   /* An object manager client is used to monitor for new objects exported by
-   * the Qemu instance. Those objects are then wrapped by MksDevice objects
+   * the QEMU instance. Those objects are then wrapped by MksDevice objects
    * as necessary and exported to consumers via @devices.
    */
   GDBusObjectManager *object_manager;
@@ -365,8 +365,7 @@ mks_session_class_init (MksSessionClass *klass)
   /**
    * MksSession:connection:
    *
-   * The "connection" property contains the #GDBusConnection that is used
+   * The [class@Gio.DBusConnection] that is used to communicate with QEMU.
-   * to communicate with Qemu.
    */
   properties [PROP_CONNECTION] =
     g_param_spec_object ("connection", NULL, NULL,
@@ -376,8 +375,8 @@ mks_session_class_init (MksSessionClass *klass)
   /**
    * MksSession:devices:
    *
-   * The "devices" property contains a #GListModel of devices that have been
+   * A [iface@Gio.ListModel] of devices that have been
-   * discovered on the #GDBusConnection to Qemu.
+   * discovered on the [class@Gio.DBusConnection] to QEMU.
    */
   properties [PROP_DEVICES] =
     g_param_spec_object ("devices", NULL, NULL,
@@ -387,8 +386,7 @@ mks_session_class_init (MksSessionClass *klass)
   /**
    * MksSession:name:
    *
-   * The "name" property is the named of the VM as specified by the
+   * The VM name as specified by the QEMU instance.
-   * Qemu instance.
    */
   properties [PROP_NAME] =
     g_param_spec_string ("name", NULL, NULL,
@@ -398,8 +396,7 @@ mks_session_class_init (MksSessionClass *klass)
   /**
    * MksSession:uuid:
    *
-   * The "uuid" property is the unique identifier as specified by the
+   * The VM unique identifier specified by the QEMU instance.
-   * Qemu instance for the VM.
    */
   properties [PROP_UUID] =
     g_param_spec_string ("uuid", NULL, NULL,
@@ -566,7 +563,7 @@ mks_session_new_for_connection_cb (GObject      *object,
  *
  * Creates a #MksSession which communicates using @connection.
  *
- * The #GDBusConnection should be a private D-Bus connection to a Qemu
+ * The [class@Gio.DBusConnection] should be a private D-Bus connection to a QEMU
  * instance which has devices created using the "dbus" backend.
 
  * @callback will be executed when the session has been created or
@@ -574,7 +571,7 @@ mks_session_new_for_connection_cb (GObject      *object,
  *
  * This function will not block the calling thread.
  *
- * use mks_session_new_for_connection_finish() to get the result of
+ * use [ctor@Mks.Session.new_for_connection_finish] to get the result of
  * this operation.
  */
 void
@@ -610,7 +607,7 @@ mks_session_new_for_connection (GDBusConnection     *connection,
  * @result: a #GAsyncResult provided to callback
  * @error: (nullable): a location for a #GError or %NULL
  *
- * Completes a request to create a #MksSession for a #GDBusConnection.
+ * Completes a request to create a #MksSession for a [class@Gio.DBusConnection].
  *
  * Returns: (transfer full): a #MksSession if successful; otherwise %NULL
  *   and @error is set.
@@ -626,13 +623,13 @@ mks_session_new_for_connection_finish (GAsyncResult  *result,
 
 /**
  * mks_session_new_for_connection_sync:
- * @connection: a private #GDBusConnetion to a Qemu instance
+ * @connection: a private #GDBusConnetion to a QEMU instance
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: (nullable): a location for a #GError, or %NULL
  *
  * Synchronously creates a new #MksSession instance.
  *
- * This may block while the Qemu instance is contacted to query for
+ * This may block while the QEMU instance is contacted to query for
  * initial devices and VM status.
  *
  * Returns: (transfer full): a #MksSession if successful; otherwise %NULL
@@ -661,7 +658,7 @@ mks_session_new_for_connection_sync (GDBusConnection  *connection,
  * mks_session_get_connection:
  * @self: a #MksSession
  *
- * Gets the #MksSession:connection property.
+ * Gets the DBus connection used for this session.
  *
  * Returns: (transfer none) (nullable): a #GDBusConnection or %NULL if
  *   the connection has not been set, or was disposed.
@@ -678,7 +675,7 @@ mks_session_get_connection (MksSession *self)
  * mks_session_get_uuid:
  * @self: a #MksSession
  *
- * Gets the "uuid" property.
+ * Gets the unique identifier of the VM.
  */
 const char *
 mks_session_get_uuid (MksSession *self)
@@ -695,7 +692,7 @@ mks_session_get_uuid (MksSession *self)
  * mks_session_get_name:
  * @self: a #MksSession
  *
- * Gets the "name" property.
+ * Gets the name of the VM.
  */
 const char *
 mks_session_get_name (MksSession *self)

lib/mks-speaker.c

@@ -28,6 +28,12 @@
 #include "mks-speaker.h"
 #include "mks-util-private.h"
 
+/**
+ * MksSpeaker:
+ * 
+ * A virtualized QEMU speaker.
+ */
+
 struct _MksSpeaker
 {
   MksDevice parent_instance;
@@ -310,9 +316,8 @@ mks_speaker_class_init (MksSpeakerClass *klass)
   /**
    * MksSpeaker:muted:
    *
-   * The "muted" property denotes if audio received from the
+   * If audio received from the instance is dropped and 
-   * instance is dropped and the remote sound device should
+   * the remote sound device should attempt to be set as muted.
-   * attempt to be set as muted.
    */
   properties [PROP_MUTED] =
     g_param_spec_boolean ("muted", NULL, NULL,
@@ -348,7 +353,7 @@ mks_speaker_get_muted (MksSpeaker *self)
  * @self: a #MksSpeaker
  * @muted: if the speaker should be muted
  *
- * Sets the #MksSpeaker:muted property.
+ * Mute or un-mute the speaker.
  */
 void
 mks_speaker_set_muted (MksSpeaker *self,

tools/mks-connect.c

@@ -70,7 +70,7 @@ int
 main (int argc,
       char *argv[])
 {
-  g_autoptr(GOptionContext) context = g_option_context_new ("DBUS_ADDRESS - Connect to Qemu at DBUS_ADDRESS");
+  g_autoptr(GOptionContext) context = g_option_context_new ("DBUS_ADDRESS - Connect to QEMU at DBUS_ADDRESS");
   g_autoptr(GDBusConnection) connection = NULL;
   g_autoptr(MksSession) session = NULL;
   g_autoptr(GError) error = NULL;