[Spice-devel] [PATCH spice-gtk 5/8] docs: Add missing parameter/field descriptions
Pavel Grunt
pgrunt at redhat.com
Thu Sep 24 06:10:38 PDT 2015
---
src/channel-display.c | 6 +++---
src/channel-inputs.c | 16 ++++++++--------
src/channel-main.c | 26 ++++++++++++++------------
src/channel-playback.c | 5 +++++
src/channel-record.c | 2 +-
src/smartcard-manager.c | 3 +--
src/spice-channel.c | 20 ++++++++++----------
src/spice-channel.h | 1 +
src/spice-grabsequence.c | 4 ++--
src/spice-gtk-session.c | 4 ++--
src/spice-session.c | 10 ++++++----
src/spice-widget.c | 8 ++++----
src/usb-device-manager.h | 1 +
src/usb-device-widget.h | 1 +
14 files changed, 59 insertions(+), 48 deletions(-)
diff --git a/src/channel-display.c b/src/channel-display.c
index a65f926..c3a504f 100644
--- a/src/channel-display.c
+++ b/src/channel-display.c
@@ -392,9 +392,9 @@ static void spice_display_channel_class_init(SpiceDisplayChannelClass *klass)
/**
* spice_display_get_primary:
- * @channel:
- * @surface_id:
- * @primary:
+ * @channel: a #SpiceDisplayChannel
+ * @surface_id: a surface id
+ * @primary: a #SpiceDisplayPrimary
*
* Retrieve primary display surface @surface_id.
*
diff --git a/src/channel-inputs.c b/src/channel-inputs.c
index df1ffe1..1a6457d 100644
--- a/src/channel-inputs.c
+++ b/src/channel-inputs.c
@@ -278,7 +278,7 @@ static void channel_set_handlers(SpiceChannelClass *klass)
/**
* spice_inputs_motion:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @dx: delta X mouse coordinates
* @dy: delta Y mouse coordinates
* @button_state: SPICE_MOUSE_BUTTON_MASK flags
@@ -310,7 +310,7 @@ void spice_inputs_motion(SpiceInputsChannel *channel, gint dx, gint dy,
/**
* spice_inputs_position:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @x: X mouse coordinates
* @y: Y mouse coordinates
* @display: display channel id
@@ -343,7 +343,7 @@ void spice_inputs_position(SpiceInputsChannel *channel, gint x, gint y,
/**
* spice_inputs_button_press:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @button: a SPICE_MOUSE_BUTTON
* @button_state: SPICE_MOUSE_BUTTON_MASK flags
*
@@ -390,7 +390,7 @@ void spice_inputs_button_press(SpiceInputsChannel *channel, gint button,
/**
* spice_inputs_button_release:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @button: a SPICE_MOUSE_BUTTON
* @button_state: SPICE_MOUSE_BUTTON_MASK flags
*
@@ -437,7 +437,7 @@ void spice_inputs_button_release(SpiceInputsChannel *channel, gint button,
/**
* spice_inputs_key_press:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @scancode: a PC XT (set 1) key scancode. For scancodes with an %0xe0
* prefix, drop the prefix and OR the scancode with %0x100.
*
@@ -463,7 +463,7 @@ void spice_inputs_key_press(SpiceInputsChannel *channel, guint scancode)
/**
* spice_inputs_key_release:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @scancode: a PC XT (set 1) key scancode. For scancodes with an %0xe0
* prefix, drop the prefix and OR the scancode with %0x100.
*
@@ -489,7 +489,7 @@ void spice_inputs_key_release(SpiceInputsChannel *channel, guint scancode)
/**
* spice_inputs_key_press_and_release:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @scancode: a PC XT (set 1) key scancode. For scancodes with an %0xe0
* prefix, drop the prefix and OR the scancode with %0x100.
*
@@ -562,7 +562,7 @@ static SpiceMsgOut* set_key_locks(SpiceInputsChannel *channel, guint locks)
/**
* spice_inputs_set_key_locks:
- * @channel:
+ * @channel: a #SpiceInputsChannel
* @locks: #SpiceInputsLock modifiers flags
*
* Set the keyboard locks on the guest (Caps, Num, Scroll..)
diff --git a/src/channel-main.c b/src/channel-main.c
index 2ec6457..b1c19c0 100644
--- a/src/channel-main.c
+++ b/src/channel-main.c
@@ -1042,7 +1042,7 @@ static void monitors_align(VDAgentMonConfig *monitors, int nmonitors)
/**
* spice_main_send_monitor_config:
- * @channel:
+ * @channel: a #SpiceMainChannel
*
* Send monitors configuration previously set with
* spice_main_set_display() and spice_main_set_display_enabled()
@@ -2565,7 +2565,7 @@ static void spice_main_handle_msg(SpiceChannel *channel, SpiceMsgIn *msg)
/**
* spice_main_agent_test_capability:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @cap: an agent capability identifier
*
* Test capability of a remote agent.
@@ -2581,7 +2581,7 @@ gboolean spice_main_agent_test_capability(SpiceMainChannel *channel, guint32 cap
/**
* spice_main_update_display:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @id: display ID
* @x: x position
* @y: y position
@@ -2624,7 +2624,7 @@ void spice_main_update_display(SpiceMainChannel *channel, int id,
/**
* spice_main_set_display:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @id: display ID
* @x: x position
* @y: y position
@@ -2642,7 +2642,7 @@ void spice_main_set_display(SpiceMainChannel *channel, int id,
/**
* spice_main_clipboard_grab:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @types: an array of #VD_AGENT_CLIPBOARD types available in the clipboard
* @ntypes: the number of @types
*
@@ -2657,7 +2657,7 @@ void spice_main_clipboard_grab(SpiceMainChannel *channel, guint32 *types, int nt
/**
* spice_main_clipboard_selection_grab:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @selection: one of the clipboard #VD_AGENT_CLIPBOARD_SELECTION_*
* @types: an array of #VD_AGENT_CLIPBOARD types available in the clipboard
* @ntypes: the number of @types
@@ -2678,7 +2678,7 @@ void spice_main_clipboard_selection_grab(SpiceMainChannel *channel, guint select
/**
* spice_main_clipboard_release:
- * @channel:
+ * @channel: a #SpiceMainChannel
*
* Release the clipboard (for example, when the client loses the
* clipboard grab): Inform the guest no clipboard data is available.
@@ -2692,7 +2692,7 @@ void spice_main_clipboard_release(SpiceMainChannel *channel)
/**
* spice_main_clipboard_selection_release:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @selection: one of the clipboard #VD_AGENT_CLIPBOARD_SELECTION_*
*
* Release the clipboard (for example, when the client loses the
@@ -2716,7 +2716,7 @@ void spice_main_clipboard_selection_release(SpiceMainChannel *channel, guint sel
/**
* spice_main_clipboard_notify:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @type: a #VD_AGENT_CLIPBOARD type
* @data: clipboard data
* @size: data length in bytes
@@ -2734,7 +2734,7 @@ void spice_main_clipboard_notify(SpiceMainChannel *channel,
/**
* spice_main_clipboard_selection_notify:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @selection: one of the clipboard #VD_AGENT_CLIPBOARD_SELECTION_*
* @type: a #VD_AGENT_CLIPBOARD type
* @data: clipboard data
@@ -2756,7 +2756,7 @@ void spice_main_clipboard_selection_notify(SpiceMainChannel *channel, guint sele
/**
* spice_main_clipboard_request:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @type: a #VD_AGENT_CLIPBOARD type
*
* Request clipboard data of @type from the guest. The reply is sent
@@ -2771,7 +2771,7 @@ void spice_main_clipboard_request(SpiceMainChannel *channel, guint32 type)
/**
* spice_main_clipboard_selection_request:
- * @channel:
+ * @channel: a #SpiceMainChannel
* @selection: one of the clipboard #VD_AGENT_CLIPBOARD_SELECTION_*
* @type: a #VD_AGENT_CLIPBOARD type
*
@@ -2996,6 +2996,7 @@ static void file_xfer_send_start_msg_async(SpiceMainChannel *channel,
/**
* spice_main_file_copy_async:
+ * @channel: a #SpiceMainChannel
* @sources: #GFile to be transfer
* @flags: set of #GFileCopyFlags
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
@@ -3058,6 +3059,7 @@ void spice_main_file_copy_async(SpiceMainChannel *channel,
/**
* spice_main_file_copy_finish:
+ * @channel: a #SpiceMainChannel
* @result: a #GAsyncResult.
* @error: a #GError, or %NULL
*
diff --git a/src/channel-playback.c b/src/channel-playback.c
index d8a181e..ddcb757 100644
--- a/src/channel-playback.c
+++ b/src/channel-playback.c
@@ -449,6 +449,11 @@ static void channel_set_handlers(SpiceChannelClass *klass)
spice_channel_set_handlers(klass, handlers, G_N_ELEMENTS(handlers));
}
+/**
+ * spice_playback_channel_set_delay:
+ * @channel: a #SpicePlaybackChannel
+ * @delay_ms: the delay in ms
+ **/
void spice_playback_channel_set_delay(SpicePlaybackChannel *channel, guint32 delay_ms)
{
SpicePlaybackChannelPrivate *c;
diff --git a/src/channel-record.c b/src/channel-record.c
index e581aed..a44c860 100644
--- a/src/channel-record.c
+++ b/src/channel-record.c
@@ -309,7 +309,7 @@ static void spice_record_start_mark(SpiceRecordChannel *channel, uint32_t time)
/**
* spice_record_send_data:
- * @channel:
+ * @channel: a #SpiceRecordChannel
* @data: PCM data
* @bytes: size of @data
* @time: stream timestamp
diff --git a/src/smartcard-manager.c b/src/smartcard-manager.c
index 9e228e9..0cce42b 100644
--- a/src/smartcard-manager.c
+++ b/src/smartcard-manager.c
@@ -596,8 +596,7 @@ gboolean spice_smartcard_reader_remove_card(SpiceSmartcardReader *reader)
/**
* spice_smartcard_manager_get_readers:
- *
- * manager: a #SpiceSmartcardManager
+ * @manager: a #SpiceSmartcardManager
*
* Gets the list of smartcard readers that are currently available, they
* can be either software (emulated) readers, or hardware ones.
diff --git a/src/spice-channel.c b/src/spice-channel.c
index e254b41..ce0923f 100644
--- a/src/spice-channel.c
+++ b/src/spice-channel.c
@@ -2060,7 +2060,7 @@ SpiceChannel *spice_channel_new(SpiceSession *s, int type, int id)
/**
* spice_channel_destroy:
- * @channel:
+ * @channel: a #SpiceChannel
*
* Disconnect and unref the @channel.
*
@@ -2284,7 +2284,7 @@ static int spice_channel_load_ca(SpiceChannel *channel)
/**
* spice_channel_get_error:
- * @channel:
+ * @channel: a #SpiceChannel
*
* Retrieves the #GError currently set on channel, if the #SpiceChannel
* is in error state and can provide additional error details.
@@ -2527,7 +2527,7 @@ static gboolean channel_connect(SpiceChannel *channel, gboolean tls)
/**
* spice_channel_connect:
- * @channel:
+ * @channel: a #SpiceChannel
*
* Connect the channel, using #SpiceSession connection informations
*
@@ -2548,7 +2548,7 @@ gboolean spice_channel_connect(SpiceChannel *channel)
/**
* spice_channel_open_fd:
- * @channel:
+ * @channel: a #SpiceChannel
* @fd: a file descriptor (socket) or -1.
* request mechanism
*
@@ -2661,7 +2661,7 @@ void spice_channel_reset(SpiceChannel *channel, gboolean migrating)
/**
* spice_channel_disconnect:
- * @channel:
+ * @channel: a #SpiceChannel
* @reason: a channel event emitted on main context (or #SPICE_CHANNEL_NONE)
*
* Close the socket and reset connection specific data. Finally, emit
@@ -2716,8 +2716,8 @@ static gboolean test_capability(GArray *caps, guint32 cap)
/**
* spice_channel_test_capability:
- * @channel:
- * @cap:
+ * @channel: a #SpiceChannel
+ * @cap: a capability
*
* Test availability of remote "channel kind capability".
*
@@ -2735,8 +2735,8 @@ gboolean spice_channel_test_capability(SpiceChannel *self, guint32 cap)
/**
* spice_channel_test_common_capability:
- * @channel:
- * @cap:
+ * @channel: a #SpiceChannel
+ * @cap: a capability
*
* Test availability of remote "common channel capability".
*
@@ -2767,7 +2767,7 @@ static void set_capability(GArray *caps, guint32 cap)
/**
* spice_channel_set_capability:
- * @channel:
+ * @channel: a #SpiceChannel
* @cap: a capability
*
* Enable specific channel-kind capability.
diff --git a/src/spice-channel.h b/src/spice-channel.h
index e0ce443..6f8682e 100644
--- a/src/spice-channel.h
+++ b/src/spice-channel.h
@@ -39,6 +39,7 @@ typedef struct _SpiceMsgOut SpiceMsgOut;
* SpiceChannelEvent:
* @SPICE_CHANNEL_NONE: no event, or ignored event
* @SPICE_CHANNEL_OPENED: connection is authentified and ready
+ * @SPICE_CHANNEL_SWITCHING: disconnecting from the current host and connecting to the target host.
* @SPICE_CHANNEL_CLOSED: connection is closed normally (sent if channel was ready)
* @SPICE_CHANNEL_ERROR_CONNECT: connection error
* @SPICE_CHANNEL_ERROR_TLS: SSL error
diff --git a/src/spice-grabsequence.c b/src/spice-grabsequence.c
index 39adfb0..ac97e88 100644
--- a/src/spice-grabsequence.c
+++ b/src/spice-grabsequence.c
@@ -121,7 +121,7 @@ SpiceGrabSequence *spice_grab_sequence_copy(SpiceGrabSequence *srcSequence)
/**
* spice_grab_sequence_free:
- * @sequence:
+ * @sequence: a #SpiceGrabSequence
*
* Free @sequence.
**/
@@ -134,7 +134,7 @@ void spice_grab_sequence_free(SpiceGrabSequence *sequence)
/**
* spice_grab_sequence_as_string:
- * @sequence:
+ * @sequence: a #SpiceGrabSequence
*
* Returns: (transfer full): a newly allocated string representing the key sequence
**/
diff --git a/src/spice-gtk-session.c b/src/spice-gtk-session.c
index 0937434..90f5116 100644
--- a/src/spice-gtk-session.c
+++ b/src/spice-gtk-session.c
@@ -1147,7 +1147,7 @@ SpiceGtkSession *spice_gtk_session_get(SpiceSession *session)
/**
* spice_gtk_session_copy_to_guest:
- * @self:
+ * @self: #SpiceGtkSession
*
* Copy client-side clipboard to guest clipboard.
*
@@ -1169,7 +1169,7 @@ void spice_gtk_session_copy_to_guest(SpiceGtkSession *self)
/**
* spice_gtk_session_paste_from_guest:
- * @self:
+ * @self: #SpiceGtkSession
*
* Copy guest clipboard to client-side clipboard.
*
diff --git a/src/spice-session.c b/src/spice-session.c
index 887b066..1626539 100644
--- a/src/spice-session.c
+++ b/src/spice-session.c
@@ -1542,7 +1542,7 @@ SpiceSession *spice_session_new_from_session(SpiceSession *session)
/**
* spice_session_connect:
- * @session:
+ * @session: a #SpiceSession
*
* Open the session using the #SpiceSession:host and
* #SpiceSession:port.
@@ -1575,7 +1575,7 @@ gboolean spice_session_connect(SpiceSession *session)
/**
* spice_session_open_fd:
- * @session:
+ * @session: a #SpiceSession
* @fd: a file descriptor (socket) or -1
*
* Open the session using the provided @fd socket file
@@ -1593,7 +1593,7 @@ gboolean spice_session_connect(SpiceSession *session)
* @fd this call since you will have to hook to SpiceChannel::open-fd signal
* anyway.
*
- * Returns:
+ * Returns: %TRUE on success.
**/
gboolean spice_session_open_fd(SpiceSession *session, int fd)
{
@@ -1922,7 +1922,7 @@ static gboolean session_disconnect_idle(SpiceSession *self)
/**
* spice_session_disconnect:
- * @session:
+ * @session: a #SpiceSession
*
* Disconnect the @session, and destroy all channels.
**/
@@ -1975,6 +1975,7 @@ GList *spice_session_get_channels(SpiceSession *session)
/**
* spice_session_has_channel_type:
* @session: a #SpiceSession
+ * @type: a #SpiceChannel:channel-type
*
* See if there is a @type channel in the channels associated with this
* @session.
@@ -2656,6 +2657,7 @@ SpiceAudio *spice_audio_get(SpiceSession *session, GMainContext *context)
/**
* spice_usb_device_manager_get:
* @session: #SpiceSession for which to get the #SpiceUsbDeviceManager
+ * @err: (allow-none): a return location for #GError, or %NULL.
*
* Gets the #SpiceUsbDeviceManager associated with the passed in #SpiceSession.
* A new #SpiceUsbDeviceManager instance will be created the first time this
diff --git a/src/spice-widget.c b/src/spice-widget.c
index 34bc128..a7ff438 100644
--- a/src/spice-widget.c
+++ b/src/spice-widget.c
@@ -2563,7 +2563,7 @@ SpiceDisplay* spice_display_new_with_monitor(SpiceSession *session, gint channel
/**
* spice_display_mouse_ungrab:
- * @display:
+ * @display: a #SpiceDisplay
*
* Ungrab the mouse.
**/
@@ -2576,7 +2576,7 @@ void spice_display_mouse_ungrab(SpiceDisplay *display)
/**
* spice_display_copy_to_guest:
- * @display:
+ * @display: a #SpiceDisplay
*
* Copy client-side clipboard to guest clipboard.
*
@@ -2597,7 +2597,7 @@ void spice_display_copy_to_guest(SpiceDisplay *display)
/**
* spice_display_paste_from_guest:
- * @display:
+ * @display: a #SpiceDisplay
*
* Copy guest clipboard to client-side clipboard.
*
@@ -2618,7 +2618,7 @@ void spice_display_paste_from_guest(SpiceDisplay *display)
/**
* spice_display_get_pixbuf:
- * @display:
+ * @display: a #SpiceDisplay
*
* Take a screenshot of the display.
*
diff --git a/src/usb-device-manager.h b/src/usb-device-manager.h
index 5b4cfbe..8b173bb 100644
--- a/src/usb-device-manager.h
+++ b/src/usb-device-manager.h
@@ -61,6 +61,7 @@ struct _SpiceUsbDeviceManager
* @device_added: Signal class handler for the #SpiceUsbDeviceManager::device-added signal.
* @device_removed: Signal class handler for the #SpiceUsbDeviceManager::device-removed signal.
* @auto_connect_failed: Signal class handler for the #SpiceUsbDeviceManager::auto-connect-failed signal.
+ * @device_error: Signal class handler for the #SpiceUsbDeviceManager::device_error signal.
*
* Class structure for #SpiceUsbDeviceManager.
*/
diff --git a/src/usb-device-widget.h b/src/usb-device-widget.h
index b68cc6b..9143d5c 100644
--- a/src/usb-device-widget.h
+++ b/src/usb-device-widget.h
@@ -53,6 +53,7 @@ struct _SpiceUsbDeviceWidget
/**
* SpiceUsbDeviceWidgetClass:
+ * @parent_class: Parent class.
* @connect_failed: Signal class handler for the #SpiceUsbDeviceWidget::connect-failed signal.
*
* Class structure for #SpiceUsbDeviceWidget.
--
2.5.0
More information about the Spice-devel
mailing list