[gtk-vnc] Add docs for all public APIs

[Daniel P. Berrange <dberrange src gnome org>]

commit eab07279952e017341a712553946f93b58bd3b27
Author: Daniel P. Berrange <berrange redhat com>
Date:   Fri Jul 22 13:21:29 2016 +0100

    Add docs for all public APIs
    
    Signed-off-by: Daniel P. Berrange <berrange redhat com>

 src/vncaudio.c            |   24 +++-
 src/vncaudioformat.c      |   35 ++++-
 src/vncaudiopulse.c       |    8 +
 src/vncaudiosample.c      |   43 ++++-
 src/vncbaseaudio.c        |    9 +
 src/vncbaseframebuffer.c  |   17 ++
 src/vnccairoframebuffer.c |   21 +++
 src/vnccolormap.c         |   71 +++++++-
 src/vnccolormap.h         |    2 +-
 src/vncconnection.c       |  382 +++++++++++++++++++++++++++++++++++++++-
 src/vnccursor.c           |   60 +++++++
 src/vnccursor.h           |    2 +-
 src/vncdisplay.c          |  431 ++++++++++++++++++++++++++++++++++++++++++++-
 src/vncframebuffer.c      |  134 ++++++++++++++-
 src/vncgrabsequence.c     |   42 ++++-
 src/vncimageframebuffer.c |   18 ++
 src/vncpixelformat.c      |   28 +++-
 src/vncutil.c             |   46 +++++
 18 files changed, 1332 insertions(+), 41 deletions(-)
---
diff --git a/src/vncaudio.c b/src/vncaudio.c
index cb1cbe0..38b18a3 100644
--- a/src/vncaudio.c
+++ b/src/vncaudio.c
@@ -22,17 +22,39 @@
 
 #include "vncaudio.h"
 
-
+/**
+ * vnc_audio_playback_start:
+ * @aud: (transfer none): the audio object
+ * @format: (transfer none): the new audio format
+ *
+ * Indicate that the remote desktop is about to start
+ * audio playback in format @format.
+ */
 void vnc_audio_playback_start(VncAudio *aud, VncAudioFormat *format)
 {
     VNC_AUDIO_GET_INTERFACE(aud)->playback_start(aud, format);
 }
 
+
+/**
+ * vnc_audio_playback_stop
+ * @aud: (transfer none): the audio object
+ *
+ * Indicate that the remote desktop has completed
+ * audio playback
+ */
 void vnc_audio_playback_stop(VncAudio *aud)
 {
     VNC_AUDIO_GET_INTERFACE(aud)->playback_stop(aud);
 }
 
+/**
+ * vnc_audio_playback_data:
+ * @aud: (transfer none): the audio object
+ * @sample: (transfer none): the audio sample
+ *
+ * Request playback of a single audio sample in @sample
+ */
 void vnc_audio_playback_data(VncAudio *aud, VncAudioSample *sample)
 {
     VNC_AUDIO_GET_INTERFACE(aud)->playback_data(aud, sample);
diff --git a/src/vncaudioformat.c b/src/vncaudioformat.c
index 43e31cf..1036f85 100644
--- a/src/vncaudioformat.c
+++ b/src/vncaudioformat.c
@@ -37,6 +37,16 @@ GType vnc_audio_format_get_type(void)
 }
 
 
+/**
+ * vnc_audio_format_new:
+ *
+ * Allocate a new VNC audio format struct whose
+ * contents is initialized to all zeros. The
+ * struct must be released using vnc_audio_format_free
+ * when no longer required
+ *
+ * Returns: (transfer full): the new audio format struct
+ */
 VncAudioFormat *vnc_audio_format_new(void)
 {
     VncAudioFormat *format;
@@ -47,16 +57,33 @@ VncAudioFormat *vnc_audio_format_new(void)
 }
 
 
-VncAudioFormat *vnc_audio_format_copy(VncAudioFormat *srcFormat)
+/**
+ * vnc_audio_format_copy:
+ * @format: the format to copy
+ *
+ * Allocate a new VNC audio format struct whose
+ * contents is initialized with the data found
+ * in @format. The struct must be released using
+ * vnc_audio_format_free when no longer required.
+ *
+ * Returns: (transfer full): the new audio format struct
+ */
+VncAudioFormat *vnc_audio_format_copy(VncAudioFormat *format)
 {
-    VncAudioFormat *format;
+    VncAudioFormat *ret;
 
-    format = g_slice_dup(VncAudioFormat, srcFormat);
+    ret = g_slice_dup(VncAudioFormat, format);
 
-    return format;
+    return ret;
 }
 
 
+/**
+ * vnc_audio_format_free:
+ * @format: the format to free
+ *
+ * Release the memory associated with @format
+ */
 void vnc_audio_format_free(VncAudioFormat *format)
 {
     g_slice_free(VncAudioFormat, format);
diff --git a/src/vncaudiopulse.c b/src/vncaudiopulse.c
index abcc66b..80982da 100644
--- a/src/vncaudiopulse.c
+++ b/src/vncaudiopulse.c
@@ -155,6 +155,14 @@ void vnc_audio_pulse_init(VncAudioPulse *fb)
 }
 
 
+/**
+ * vnc_audio_pulse_new:
+ *
+ * Create a new VNC audio object able to play
+ * audio samples via pulseaudio
+ *
+ * Returns: (transfer full): the new audio object
+ */
 VncAudioPulse *vnc_audio_pulse_new(void)
 {
     return VNC_AUDIO_PULSE(g_object_new(VNC_TYPE_AUDIO_PULSE,
diff --git a/src/vncaudiosample.c b/src/vncaudiosample.c
index 4796b09..fc11c92 100644
--- a/src/vncaudiosample.c
+++ b/src/vncaudiosample.c
@@ -39,6 +39,18 @@ GType vnc_audio_sample_get_type(void)
 }
 
 
+/**
+ * vnc_audio_sample_new:
+ * @capacity: the sample size in bytes
+ *
+ * Allocate a new audio sample able to store @capacity
+ * bytes of audio data.
+ *
+ * The returned sample must be freed with
+ * vnc_audio_sample_free when no longer required.
+ *
+ * Returns: (transfer full): the new audio sample.
+ */
 VncAudioSample *vnc_audio_sample_new(guint32 capacity)
 {
     VncAudioSample *sample;
@@ -52,18 +64,37 @@ VncAudioSample *vnc_audio_sample_new(guint32 capacity)
 }
 
 
-VncAudioSample *vnc_audio_sample_copy(VncAudioSample *srcSample)
+/**
+ * vnc_audio_sample_copy:
+ * @sample: the sample to copy
+ *
+ * Allocate a new audio sample, initializing it with a copy
+ * of the data in @sample.
+ *
+ * The returned sample must be freed with
+ * vnc_audio_sample_free when no longer required.
+ *
+ * Returns: (transfer full): the new audio sample.
+ */
+VncAudioSample *vnc_audio_sample_copy(VncAudioSample *sample)
 {
-    VncAudioSample *sample;
+    VncAudioSample *ret;
 
-    sample = g_slice_dup(VncAudioSample, srcSample);
-    sample->data = g_new0(guint8, srcSample->capacity);
-    memcpy(sample->data, srcSample->data, srcSample->length);
+    ret = g_slice_dup(VncAudioSample, sample);
+    ret->data = g_new0(guint8, sample->capacity);
+    memcpy(ret->data, sample->data, sample->length);
 
-    return sample;
+    return ret;
 }
 
 
+/**
+ * vnc_audio_sample_free:
+ * @sample: the sample to free
+ *
+ * Release memory associated with the audio sample
+ * @sample
+ */
 void vnc_audio_sample_free(VncAudioSample *sample)
 {
     g_free(sample->data);
diff --git a/src/vncbaseaudio.c b/src/vncbaseaudio.c
index dd01b14..c1fb210 100644
--- a/src/vncbaseaudio.c
+++ b/src/vncbaseaudio.c
@@ -88,6 +88,15 @@ void vnc_base_audio_init(VncBaseAudio *fb)
 }
 
 
+/**
+ * vnc_base_audio_new:
+ *
+ * Create a new generic VNC audio object, which will emit
+ * signals when key audio events occur. Callers can connect
+ * to these signals to provide playback facilities.
+ *
+ * Returns: (transfer full): a new audio object
+ */
 VncBaseAudio *vnc_base_audio_new(void)
 {
     return VNC_BASE_AUDIO(g_object_new(VNC_TYPE_BASE_AUDIO,
diff --git a/src/vncbaseframebuffer.c b/src/vncbaseframebuffer.c
index d487a3d..64344db 100644
--- a/src/vncbaseframebuffer.c
+++ b/src/vncbaseframebuffer.c
@@ -331,6 +331,23 @@ void vnc_base_framebuffer_init(VncBaseFramebuffer *fb)
 }
 
 
+/**
+ * vnc_base_framebuffer_new:
+ * @buffer: (array): the buffer representing the screen
+ * @width: the width of the screen
+ * @height: the height of the screen
+ * @rowstride: the number of bytes per line in @buffer
+ * @localFormat: the format for data stored in @buffer
+ * @remoteFormat: the format for data before storage in @buffer
+ *
+ * Allocate a new general purpose framebuffer object storing
+ * screen updates in @buffer. @buffer must be @height *
+ * @rowstride bytes in size. The returned object will
+ * store a pointer to @buffer, so it should not be free'd
+ * for as long as the framebuffer object exists
+ *
+ * Returns: (transfer full): the new framebuffer
+ */
 VncBaseFramebuffer *vnc_base_framebuffer_new(guint8 *buffer,
                                              guint16 width,
                                              guint16 height,
diff --git a/src/vnccairoframebuffer.c b/src/vnccairoframebuffer.c
index 75cf7d9..9ebe7db 100644
--- a/src/vnccairoframebuffer.c
+++ b/src/vnccairoframebuffer.c
@@ -125,6 +125,18 @@ void vnc_cairo_framebuffer_init(VncCairoFramebuffer *fb)
 }
 
 
+/**
+ * vnc_cairo_framebuffer_new:
+ * @width: the remote desktop width
+ * @height: the remote desktop height
+ * @remoteFormat: (transfer none): the remote pixel format
+ *
+ * Allocate a new framebuffer object which will render the
+ * remote desktop into a cairo image surface (@width * @height)
+ * in size.
+ *
+ * Returns: (transfer full): the new frame buffer object
+ */
 VncCairoFramebuffer *vnc_cairo_framebuffer_new(guint16 width, guint16 height,
                                                const VncPixelFormat *remoteFormat)
 {
@@ -160,6 +172,15 @@ VncCairoFramebuffer *vnc_cairo_framebuffer_new(guint16 width, guint16 height,
 }
 
 
+/**
+ * vnc_cairo_framebuffer_get_surface:
+ * @fb: the framebuffer object
+ *
+ * Get the cairo surface in which the remote desktop is
+ * being rendered.
+ *
+ * Returns: (transfer none): the cairo surface
+ */
 cairo_surface_t *vnc_cairo_framebuffer_get_surface(VncCairoFramebuffer *fb)
 {
     VncCairoFramebufferPrivate *priv = fb->priv;
diff --git a/src/vnccolormap.c b/src/vnccolormap.c
index 222e9e0..25cd2fc 100644
--- a/src/vnccolormap.c
+++ b/src/vnccolormap.c
@@ -39,6 +39,20 @@ GType vnc_color_map_get_type(void)
 }
 
 
+/**
+ * vnc_color_map_new:
+ * @offset: the offset at which the color map starts
+ * @size: the number of entries
+ *
+ * Allocate a new colour map object able to store colour
+ * map entries with indexes in the range @offset to
+ * @offset + @size.
+ *
+ * The color map must be freed with vnc_color_map_free
+ * when no longer required.
+ *
+ * Returns: (transfer full): the new color map
+ */
 VncColorMap *vnc_color_map_new(guint16 offset, guint16 size)
 {
     VncColorMap *map;
@@ -52,25 +66,53 @@ VncColorMap *vnc_color_map_new(guint16 offset, guint16 size)
 }
 
 
-VncColorMap *vnc_color_map_copy(VncColorMap *srcMap)
+/**
+ * vnc_color_map_copy:
+ * @map: (transfer none): the original color map
+ *
+ * Allocate a new color map initializing it with a
+ * copy of the data stored in @map.
+ *
+ * Returns: (transfer full): the new color map
+ */
+VncColorMap *vnc_color_map_copy(VncColorMap *map)
 {
-    VncColorMap *map;
+    VncColorMap *ret;
 
-    map = g_slice_dup(VncColorMap, srcMap);
-    map->colors = g_new0(VncColorMapEntry, srcMap->size);
-    memcpy(map->colors, srcMap->colors,
-           sizeof(VncColorMapEntry) * map->size);
+    ret = g_slice_dup(VncColorMap, map);
+    ret->colors = g_new0(VncColorMapEntry, map->size);
+    memcpy(ret->colors, map->colors,
+           sizeof(VncColorMapEntry) * ret->size);
 
-    return map;
+    return ret;
 }
 
-
+/**
+ * vnc_color_map_free:
+ * @map: the color map object
+ *
+ * Release the memory associated with the
+ * color map @map
+ */
 void vnc_color_map_free(VncColorMap *map)
 {
     g_slice_free(VncColorMap, map);
 }
 
 
+/**
+ * vnc_color_map_set:
+ * @map: the color map object
+ * @idx: the index to set
+ * @red: the new red value
+ * @green: the new green value
+ * @blue: the new blue value
+ *
+ * Update the RGB value associated with the
+ * color map entry at position @idx.
+ *
+ * Returns: TRUE if @idx was in range, FALSE otherwise
+ */
 gboolean vnc_color_map_set(VncColorMap *map,
                            guint16 idx,
                            guint16 red,
@@ -88,6 +130,19 @@ gboolean vnc_color_map_set(VncColorMap *map,
 }
 
 
+/**
+ * vnc_color_map_lookup:
+ * @map: the color map object
+ * @idx: the index to set
+ * @red: pointer to hold the red value
+ * @green: pointer to hold the green value
+ * @blue: pointer to hold the blue value
+ *
+ * Lookup the RGB values associated with the
+ * colour map entry at position @idx
+ *
+ * Returns: TRUE if @idx was in range, FALSE otherwise
+ */
 gboolean vnc_color_map_lookup(VncColorMap *map,
                               guint16 idx,
                               guint16 *red,
diff --git a/src/vnccolormap.h b/src/vnccolormap.h
index 3bbe77a..6f06098 100644
--- a/src/vnccolormap.h
+++ b/src/vnccolormap.h
@@ -51,7 +51,7 @@ struct _VncColorMapEntry {
 
 GType vnc_color_map_get_type(void);
 
-VncColorMap *vnc_color_map_new(guint16 offset, guint16 nentries);
+VncColorMap *vnc_color_map_new(guint16 offset, guint16 size);
 VncColorMap *vnc_color_map_copy(VncColorMap *map);
 void vnc_color_map_free(VncColorMap *map);
 
diff --git a/src/vncconnection.c b/src/vncconnection.c
index 21b312e..b357fc5 100644
--- a/src/vncconnection.c
+++ b/src/vncconnection.c
@@ -1472,6 +1472,15 @@ static void vnc_connection_ledstate_change(VncConnection *conn)
 
 /* initialize function */
 
+/**
+ * vnc_connection_has_error:
+ * @conn: (transfer none): the connection object
+ *
+ * Determine if the current connection is in an error
+ * state
+ *
+ * Returns: TRUE if an error has occurred, FALSE otherwise
+ */
 gboolean vnc_connection_has_error(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1479,6 +1488,14 @@ gboolean vnc_connection_has_error(VncConnection *conn)
     return priv->has_error;
 }
 
+/**
+ * vnc_connection_get_pixel_format:
+ * @conn: (transfer none): the connection object
+ *
+ * Get a specification of the current pixel format
+ *
+ * Returns: (transfer none): the current pixel format
+ */
 const VncPixelFormat *vnc_connection_get_pixel_format(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1487,6 +1504,18 @@ const VncPixelFormat *vnc_connection_get_pixel_format(VncConnection *conn)
 }
 
 
+/**
+ * vnc_connection_set_shared:
+ * @conn: (transfer none): the connection object
+ * @sharedFlag: the new sharing state
+ *
+ * Set the shared state for the connection. A TRUE value
+ * allow allow this client to co-exist with other existing
+ * clients. A FALSE value will cause other clients to be
+ * dropped
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_shared(VncConnection *conn, gboolean sharedFlag)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1500,6 +1529,14 @@ gboolean vnc_connection_set_shared(VncConnection *conn, gboolean sharedFlag)
 }
 
 
+/**
+ * vnc_connection_get_shared:
+ * @conn: (transfer none): the connection object
+ *
+ * Get the sharing state for the connection
+ *
+ * Returns: TRUE if other clients are permitted, FALSE otherwise
+ */
 gboolean vnc_connection_get_shared(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1575,6 +1612,19 @@ static void vnc_connection_buffered_flush(VncConnection *conn)
     g_io_wakeup(&priv->wait);
 }
 
+/**
+ * vnc_connection_set_pixel_format:
+ * @conn: (transfer none): the connection object
+ * @fmt: (transfer none): the new pixel format
+ *
+ * Tell the server what pixel format  to use for
+ * framebuffer updates. It is only safe to use this
+ * when no framebuffer updates are pending, otherwise
+ * it is impossible to determine when the server has
+ * switched over to using the new format.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_pixel_format(VncConnection *conn,
                                          const VncPixelFormat *fmt)
 {
@@ -1606,6 +1656,16 @@ gboolean vnc_connection_set_pixel_format(VncConnection *conn,
 }
 
 
+/**
+ * vnc_connection_set_audio:
+ * @conn: (transfer none): the connection object
+ * @audio: (transfer none): the audio sink
+ *
+ * Set the audio sink to use for playing back audio from
+ * the remote session.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_audio(VncConnection *conn,
                                   VncAudio *audio)
 {
@@ -1636,6 +1696,19 @@ static void vnc_connection_send_audio_format(VncConnection *conn)
     priv->audio_format_pending=FALSE;
 }
 
+/**
+ * vnc_connection_set_audio_format:
+ * @conn: (transfer none): the connection object
+ * @fmt: (transfer none): the audio format
+ *
+ * Set the audio format specification to use for playback
+ * from the remote session. The format should only be set
+ * when the audio stream is not active, otherwise it will
+ * be impossible to determine when the server has switched
+ * to sending data in the new format
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_audio_format(VncConnection *conn,
                                          const VncAudioFormat *fmt)
 {
@@ -1651,6 +1724,14 @@ gboolean vnc_connection_set_audio_format(VncConnection *conn,
 }
 
 
+/**
+ * vnc_connection_get_audio_format:
+ * @conn: (transfer none): the connection object
+ *
+ * Get the current audio format specification
+ *
+ * Returns: (transfer none): the current audio format
+ */
 const VncAudioFormat *vnc_connection_get_audio_format(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1658,6 +1739,15 @@ const VncAudioFormat *vnc_connection_get_audio_format(VncConnection *conn)
 }
 
 
+/**
+ * vnc_connection_audio_enable:
+ * @conn: (transfer none): the connection object
+ *
+ * Tell the server that it is permitted to send audio
+ * data.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_audio_enable(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1675,6 +1765,17 @@ gboolean vnc_connection_audio_enable(VncConnection *conn)
     return !vnc_connection_has_error(conn);
 }
 
+
+/**
+ * vnc_connection_audio_disable:
+ * @conn: (transfer none): the connection object
+ *
+ * Tell the server that it is no longer permitted to send
+ * audio. The client may continue to receive audio for a
+ * time after this, since packets may already be in flight.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_audio_disable(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1694,6 +1795,18 @@ gboolean vnc_connection_audio_disable(VncConnection *conn)
 }
 
 
+/**
+ * vnc_connection_set_encodings:
+ * @conn: (transfer none): the connection object
+ * @n_encoding: number of entries in @encoding
+ * @encoding: (transfer none)(array length=n_encoding): the list of permitted encodings
+ *
+ * Inform the server of the list of encodings that it is
+ * allowed to send. This should be done before requesting
+ * any framebuffer updates
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_encodings(VncConnection *conn, int n_encoding, gint32 *encoding)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -1737,6 +1850,22 @@ gboolean vnc_connection_set_encodings(VncConnection *conn, int n_encoding, gint3
 }
 
 
+/**
+ * vnc_connection_framebuffer_update_request:
+ * @conn: (transfer none): the connection object
+ * @incremental: TRUE to only receive region with changes
+ * @x: horizontal offset to region of update
+ * @y: vertical offset to region of update
+ * @width: horizontal size of region of update
+ * @height: vertical size of region of update
+ *
+ * Request that the server send a framebuffer update when the
+ * region positioned at (@x, @y) wth size (@width, @height)
+ * sees damage. The update sent may be a subset of the region
+ * requested, if @incremental is FALSE.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_framebuffer_update_request(VncConnection *conn,
                                                    gboolean incremental,
                                                    guint16 x, guint16 y,
@@ -1793,6 +1922,20 @@ vnc_connection_resend_framebuffer_update_request(VncConnection *conn)
 }
 
 
+/**
+ * vnc_connection_key_event:
+ * @conn: (transfer none): the connection object
+ * @down_flag: TRUE if this is a key press, FALSE for a key release
+ * @key: the X11 key code
+ * @scancode: the XT scan code
+ *
+ * Send a key press/release event to the server. By default the
+ * event will be sent with the X11 key code from @key. If the
+ * extended key event protocol extension is active, the @scancode
+ * will be sent instead.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_key_event(VncConnection *conn, gboolean down_flag,
                                   guint32 key, guint16 scancode)
 {
@@ -1817,6 +1960,18 @@ gboolean vnc_connection_key_event(VncConnection *conn, gboolean down_flag,
     return !vnc_connection_has_error(conn);
 }
 
+/**
+ * vnc_connection_pointer_event:
+ * @conn: (transfer none): the connection object
+ * @button_mask: the new state of the buttons
+ * @x: the new horizontal position of the pointer
+ * @y: the new veritical position of the pointer
+ *
+ * Send a pointer event to the server, reflecting either movement
+ * of the pointer, or a change in state of its buttons, or both.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_pointer_event(VncConnection *conn, guint8 button_mask,
                                       guint16 x, guint16 y)
 {
@@ -1828,6 +1983,18 @@ gboolean vnc_connection_pointer_event(VncConnection *conn, guint8 button_mask,
     return !vnc_connection_has_error(conn);
 }
 
+/**
+ * vnc_connection_cut_text:
+ * @conn: (transfer none): the connection object
+ * @data: (transfer none)(array length=@length): the data to send
+ * @length: the length of @data
+ *
+ * Send updated clipboard text to the server. The encoding of @data
+ * is undefined by the protocol specification, but recommended practice
+ * is to use UTF-8
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_client_cut_text(VncConnection *conn,
                                         const void *data, size_t length)
 {
@@ -4779,7 +4946,7 @@ static void vnc_connection_class_init(VncConnectionClass *klass)
 }
 
 
-void vnc_connection_init(VncConnection *conn)
+static void vnc_connection_init(VncConnection *conn)
 {
     VncConnectionPrivate *priv;
 
@@ -4795,6 +4962,14 @@ void vnc_connection_init(VncConnection *conn)
 }
 
 
+/**
+ * vnc_connection_new:
+ *
+ * Create a new connection object, which is initially
+ * in the disconnected state.
+ *
+ * Returns: (transfer full): the new connection
+ */
 VncConnection *vnc_connection_new(void)
 {
     return VNC_CONNECTION(g_object_new(VNC_TYPE_CONNECTION,
@@ -4903,6 +5078,15 @@ static void vnc_connection_close(VncConnection *conn)
     priv->has_error = FALSE;
 }
 
+
+/**
+ * vnc_connection_shutdown:
+ * @conn: (transfer none): the connection object
+ *
+ * Initiate a shutdown of the current connection
+ * by closing its socket
+ *
+ */
 void vnc_connection_shutdown(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -4927,6 +5111,15 @@ void vnc_connection_shutdown(VncConnection *conn)
         g_socket_close(priv->sock, NULL);
 }
 
+
+/**
+ * vnc_connection_is_open:
+ * @conn: (transfer none): the connection object
+ *
+ * Check if the connection is currently open
+ *
+ * Returns: TRUE if open, FALSE if closing/closed
+ */
 gboolean vnc_connection_is_open(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -4943,6 +5136,16 @@ gboolean vnc_connection_is_open(VncConnection *conn)
 }
 
 
+/**
+ * vnc_connection_is_initialized:
+ * @conn: (transfer none): the connection object
+ *
+ * Determine if the connection to the remote desktop is
+ * fully initialized and thus receiving framebuffer
+ * updates.
+ *
+ * Returns: TRUE if initialized, FALSE if closed or still negotiating
+ */
 gboolean vnc_connection_is_initialized(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5262,12 +5465,41 @@ static gboolean do_vnc_connection_open(gpointer data)
     return FALSE;
 }
 
+
+/**
+ * vnc_connection_open_fd:
+ * @conn: (transfer none): the connection object
+ * @fd: file descriptor to use for the connection
+ *
+ * Open a connection using @fd as the transport. If @fd
+ * refers to a TCP connection, it is recommended to use
+ * vnc_connection_open_fd_with_hostname instead, to
+ * provide the remote hostname. This allows use of
+ * x509 based authentication which requires a hostname
+ * to be available.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_connection_open_fd(VncConnection *conn, int fd)
 {
     return vnc_connection_open_fd_with_hostname(conn, fd, NULL);
 }
 
 
+/**
+ * vnc_connection_open_fd_with_hostname:
+ * @conn: (transfer none): the connection object
+ * @fd: file descriptor to use for the connection
+ * @hostname: (transfer none)(nullable): the host associated with the connection
+ *
+ * Open a connection using @fd as the transport. The
+ * @hostname provided should reflect the name of the
+ * host that the @fd provides a connection to. This
+ * will be used by some authentication schemes, for
+ * example x509 certificate validation against @hostname.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_connection_open_fd_with_hostname(VncConnection *conn, int fd, const char *hostname)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5289,6 +5521,17 @@ gboolean vnc_connection_open_fd_with_hostname(VncConnection *conn, int fd, const
 }
 
 
+/**
+ * vnc_connection_open_host:
+ * @conn: (transfer none): the connection object
+ * @host: (transfer none): the host name or IP address
+ * @port: (transfer none): the service name or port number
+ *
+ * Open a TCP connection to the remote desktop at @host
+ * listening on @port.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_connection_open_host(VncConnection *conn, const char *host, const char *port)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5309,6 +5552,26 @@ gboolean vnc_connection_open_host(VncConnection *conn, const char *host, const c
     return TRUE;
 }
 
+
+/**
+ * vnc_connection_open_addr:
+ * @conn: (transfer none): the connection object
+ * @addr: (transfer none): the socket address
+ * @hostname: (transfer none)(nullable): the hostname
+ *
+ * Open a socket connection to server identified by @addr.
+ * @addr may refer to either a TCP address (IPv4/6) or
+ * a UNIX socket address. The @hostname provided should
+ * reflect the name of the host that the @addr provides a
+ * connection to, if it is not already available in @addr.
+ * For example, if @addr points to a proxy server, then
+ * @hostname can be used to provide the name of the final
+ * endpoint. This will be used by some authentication
+ * schemes, for example x509 certificate validation
+ * against @hostname.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_connection_open_addr(VncConnection *conn, GSocketAddress *addr, const char *hostname)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5336,6 +5599,16 @@ gboolean vnc_connection_open_addr(VncConnection *conn, GSocketAddress *addr, con
 }
 
 
+/**
+ * vnc_connection_set_auth_type:
+ * @conn: (transfer none): the connection object
+ * @type: the requested auth type
+ *
+ * Set the authentication type to use to complete the
+ * connection.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_auth_type(VncConnection *conn, unsigned int type)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5364,6 +5637,17 @@ gboolean vnc_connection_set_auth_type(VncConnection *conn, unsigned int type)
     return !vnc_connection_has_error(conn);
 }
 
+
+/**
+ * vnc_connection_set_auth_subtype:
+ * @conn: (transfer none): the connection object
+ * @type: the auth sub-type
+ *
+ * If a multi-level authentication scheme was requested, this
+ * identifies which auth type to use for the second phase.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_auth_subtype(VncConnection *conn, unsigned int type)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5444,6 +5728,20 @@ static gboolean vnc_connection_set_credential_x509(VncConnection *conn,
     return TRUE;
 }
 
+
+/**
+ * vnc_connection_set_credential:
+ * @conn: (transfer none): the connection object
+ * @type: the authentication credential type
+ * @data: (transfer none): the value associated with the credential
+ *
+ * Sets the value of the authentication credential
+ * @type to the string @data.
+ *
+ * @type is one of the VncConnectionCredential enum vlaues
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_credential(VncConnection *conn, int type, const gchar *data)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5475,6 +5773,16 @@ gboolean vnc_connection_set_credential(VncConnection *conn, int type, const gcha
 }
 
 
+/**
+ * vnc_connection_set_framebuffer:
+ * @conn: (transfer none): the connection object
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Set the framebuffer object to which frame buffer updates
+ * will be written.
+ *
+ * Returns: TRUE if the connection is ok, FALSE if it has an error
+ */
 gboolean vnc_connection_set_framebuffer(VncConnection *conn, VncFramebuffer *fb)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5503,6 +5811,17 @@ gboolean vnc_connection_set_framebuffer(VncConnection *conn, VncFramebuffer *fb)
     return !vnc_connection_has_error(conn);
 }
 
+
+/**
+ * vnc_connection_get_name:
+ * @conn: (transfer none): the connection object
+ *
+ * Get the name of the remote display. A name will only
+ * be available once the "vnc-initialized" signal has
+ * been emitted
+ *
+ * Returns: (transfer none): the remote display name
+ */
 const char *vnc_connection_get_name(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5510,6 +5829,16 @@ const char *vnc_connection_get_name(VncConnection *conn)
     return priv->name;
 }
 
+/**
+ * vnc_connection_get_width:
+ * @conn: (transfer none): the connection object
+ *
+ * Get the width of the remote display. The width will
+ * only be set once the "vnc-initialized" signal has
+ * been emitted
+ *
+ * Returns: the desktop width
+ */
 int vnc_connection_get_width(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5517,6 +5846,16 @@ int vnc_connection_get_width(VncConnection *conn)
     return priv->width;
 }
 
+/**
+ * vnc_connection_get_height:
+ * @conn: (transfer none): the connection object
+ *
+ * Get the height of the remote display. The height will
+ * only be set once the "vnc-initialized" signal has
+ * been emitted
+ *
+ * Returns: the desktop height
+ */
 int vnc_connection_get_height(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5524,6 +5863,17 @@ int vnc_connection_get_height(VncConnection *conn)
     return priv->height;
 }
 
+/**
+ * vnc_connection_get_ext_key_event:
+ * @conn: (transfer none): the connection object
+ *
+ * Determine if the remote server supports the extended
+ * keyboard event which transmits raw XT scancodes.
+ * This will only be valid once the "vnc-initialized"
+ * signal has been emitted
+ *
+ * Returns: TRUE if supported, FALSE otherwise
+ */
 gboolean vnc_connection_get_ext_key_event(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5531,6 +5881,16 @@ gboolean vnc_connection_get_ext_key_event(VncConnection *conn)
     return priv->has_ext_key_event;
 }
 
+
+/**
+ * vnc_connection_get_cursor:
+ * @conn: the VNC connection
+ *
+ * Get the cursor currently associated with the desktop,
+ * if any.
+ *
+ * Returns: (transfer none): the cursor or NULL
+ */
 VncCursor *vnc_connection_get_cursor(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5539,6 +5899,16 @@ VncCursor *vnc_connection_get_cursor(VncConnection *conn)
 }
 
 
+/**
+ * vnc_connection_get_abs_pointer:
+ * @conn: (transfer none): the connection object
+ *
+ * Determine if the remote server supports absolute pointer
+ * motion events. This will only be valid once the
+ * "vnc-initialized" signal has been emitted.
+ *
+ * Returns: TRUE if the server supports absolute pointer mode
+ */
 gboolean vnc_connection_get_abs_pointer(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
@@ -5546,6 +5916,16 @@ gboolean vnc_connection_get_abs_pointer(VncConnection *conn)
     return priv->absPointer;
 }
 
+/**
+ * vnc_connection_get_ledstate:
+ * @conn: (transfer none): the connection object
+ *
+ * Get the current LED state bitmap. This is only
+ * valid once the "vnc-initialized" signal has been
+ * emitted.
+ *
+ * Returns: the LED state
+ */
 int vnc_connection_get_ledstate(VncConnection *conn)
 {
     VncConnectionPrivate *priv = conn->priv;
diff --git a/src/vnccursor.c b/src/vnccursor.c
index b7974e2..4dd188f 100644
--- a/src/vnccursor.c
+++ b/src/vnccursor.c
@@ -123,6 +123,22 @@ vnc_cursor_set_property(GObject      *object,
     }
 }
 
+
+/**
+ * vnc_cursor_new:
+ * @data: (array): the bitmap data for the cursor
+ * @hotx: the horizontal position of the hot point
+ * @hoty: the vertical position of the hot point
+ * @width: the width of the cursor
+ * @height: the height of the cursor
+ *
+ * Creates a new cursor using the bitmap data in @data
+ * which should be @width * @height * 4 in size. The
+ * @data parameter should be in the RGBA format, so
+ * each pixel is 32-bits in size.
+ *
+ * Returns: (transfer full): the new cursor
+ */
 VncCursor *vnc_cursor_new(guint8 *data,
                           guint16 hotx, guint16 hoty,
                           guint16 width, guint16 height)
@@ -221,6 +237,15 @@ static void vnc_cursor_init(VncCursor *cursor)
     memset(priv, 0, sizeof(VncCursorPrivate));
 }
 
+
+/**
+ * vnc_cursor_get_data:
+ * @cursor: the cursor object
+ *
+ * Get the bitmap data representing the cursor
+ *
+ * Returns: (transfer none)(array): the bitmap data
+ */
 const guint8 *vnc_cursor_get_data(VncCursor *cursor)
 {
     VncCursorPrivate *priv = cursor->priv;
@@ -228,6 +253,15 @@ const guint8 *vnc_cursor_get_data(VncCursor *cursor)
     return priv->data;
 }
 
+
+/**
+ * vnc_cursor_get_hotx:
+ * @cursor: the cursor object
+ *
+ * Get the horizontal position of the cursor hot point
+ *
+ * Returns: the horizontal position of the hot point
+ */
 guint16 vnc_cursor_get_hotx(VncCursor *cursor)
 {
     VncCursorPrivate *priv = cursor->priv;
@@ -235,6 +269,15 @@ guint16 vnc_cursor_get_hotx(VncCursor *cursor)
     return priv->hotx;
 }
 
+
+/**
+ * vnc_cursor_get_hoty:
+ * @cursor: the cursor object
+ *
+ * Get the vertical position of the cursor hot point
+ *
+ * Returns: the vertical position of the hot point
+ */
 guint16 vnc_cursor_get_hoty(VncCursor *cursor)
 {
     VncCursorPrivate *priv = cursor->priv;
@@ -243,6 +286,14 @@ guint16 vnc_cursor_get_hoty(VncCursor *cursor)
 }
 
 
+/**
+ * vnc_cursor_get_width:
+ * @cursor: the cursor object
+ *
+ * Get the width of the cursor bitmap
+ *
+ * Returns: the width of the bitmap
+ */
 guint16 vnc_cursor_get_width(VncCursor *cursor)
 {
     VncCursorPrivate *priv = cursor->priv;
@@ -250,6 +301,15 @@ guint16 vnc_cursor_get_width(VncCursor *cursor)
     return priv->width;
 }
 
+
+/**
+ * vnc_cursor_get_height:
+ * @cursor: the cursor object
+ *
+ * Get the height of the cursor bitmap
+ *
+ * Returns: the height of the bitmap
+ */
 guint16 vnc_cursor_get_height(VncCursor *cursor)
 {
     VncCursorPrivate *priv = cursor->priv;
diff --git a/src/vnccursor.h b/src/vnccursor.h
index 1cbaebc..3d7b3ef 100644
--- a/src/vnccursor.h
+++ b/src/vnccursor.h
@@ -61,7 +61,7 @@ struct _VncCursorClass
 
 
 GType vnc_cursor_get_type(void);
-VncCursor *vnc_cursor_new(guint8 *rgba24data,
+VncCursor *vnc_cursor_new(guint8 *data,
                           guint16 hotx, guint16 hoty,
                           guint16 width, guint16 height);
 
diff --git a/src/vncdisplay.c b/src/vncdisplay.c
index cd4dc4a..6590d19 100644
--- a/src/vncdisplay.c
+++ b/src/vncdisplay.c
@@ -285,6 +285,17 @@ vnc_display_set_property (GObject      *object,
         }
 }
 
+
+/**
+ * vnc_display_new:
+ *
+ * Create a new widget capable of connecting to a VNC server
+ * and displaying its contents
+ *
+ * The widget will initially be in a disconnected state
+ *
+ * Returns: (transfer full): the new VNC display widget
+ */
 GtkWidget *vnc_display_new(void)
 {
     return GTK_WIDGET(g_object_new(VNC_TYPE_DISPLAY, NULL));
@@ -660,6 +671,16 @@ static void do_pointer_ungrab(VncDisplay *obj, gboolean quiet)
         g_signal_emit(obj, signals[VNC_POINTER_UNGRAB], 0);
 }
 
+/**
+ * vnc_display_force_grab:
+ * @obj: (transfer none): the VNC display widget
+ * @enable: TRUE to force pointer grabbing, FALSE otherwise
+ *
+ * If @enable is TRUE, immediately grab the pointer.
+ * If @enable is FALSE, immediately ungrab the pointer.
+ * This overrides any automatic grabs that may have
+ * been done.
+ */
 void vnc_display_force_grab(VncDisplay *obj, gboolean enable)
 {
     if (enable)
@@ -1717,6 +1738,20 @@ static void on_disconnected(VncConnection *conn G_GNUC_UNUSED,
 }
 
 
+/**
+ * vnc_display_open_fd:
+ * @obj: (transfer none): the VNC display widget
+ * @fd: file descriptor to use for the connection
+ *
+ * Open a connection using @fd as the transport. If @fd
+ * refers to a TCP connection, it is recommended to use
+ * vnc_display_open_fd_with_hostname instead, to
+ * provide the remote hostname. This allows use of
+ * x509 based authentication which requires a hostname
+ * to be available.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_display_open_fd(VncDisplay *obj, int fd)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -1736,6 +1771,20 @@ gboolean vnc_display_open_fd(VncDisplay *obj, int fd)
 }
 
 
+/**
+ * vnc_display_open_fd_with_hostname:
+ * @obj: (transfer none): the VNC display widget
+ * @fd: file descriptor to use for the connection
+ * @hostname: (transfer none)(nullable): the host associated with the connection
+ *
+ * Open a connection using @fd as the transport. The
+ * @hostname provided should reflect the name of the
+ * host that the @fd provides a connection to. This
+ * will be used by some authentication schemes, for
+ * example x509 certificate validation against @hostname.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_display_open_fd_with_hostname(VncDisplay *obj, int fd, const char *hostname)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -1755,6 +1804,25 @@ gboolean vnc_display_open_fd_with_hostname(VncDisplay *obj, int fd, const char *
 }
 
 
+/**
+ * vnc_display_open_addr:
+ * @obj: (transfer none): the VNC display widget
+ * @addr: (transfer none): the socket address
+ * @hostname: (transfer none)(nullable): the hostname
+ *
+ * Open a socket connection to server identified by @addr.
+ * @addr may refer to either a TCP address (IPv4/6) or
+ * a UNIX socket address. The @hostname provided should
+ * reflect the name of the host that the @addr provides a
+ * connection to, if it is not already available in @addr.
+ * For example, if @addr points to a proxy server, then
+ * @hostname can be used to provide the name of the final
+ * endpoint. This will be used by some authentication
+ * schemes, for example x509 certificate validation
+ * against @hostname.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_display_open_addr(VncDisplay *obj, GSocketAddress *addr, const char *hostname)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -1774,6 +1842,17 @@ gboolean vnc_display_open_addr(VncDisplay *obj, GSocketAddress *addr, const char
 }
 
 
+/**
+ * vnc_display_open_host:
+ * @obj: (transfer none): the VNC display widget
+ * @host: (transfer none): the host name or IP address
+ * @port: (transfer none): the service name or port number
+ *
+ * Open a TCP connection to the remote desktop at @host
+ * listening on @port.
+ *
+ * Returns: TRUE if a connection was opened, FALSE if already open
+ */
 gboolean vnc_display_open_host(VncDisplay *obj, const char *host, const char *port)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -1792,6 +1871,15 @@ gboolean vnc_display_open_host(VncDisplay *obj, const char *host, const char *po
     return TRUE;
 }
 
+
+/**
+ * vnc_display_is_open:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Check if the connection for the display is currently open
+ *
+ * Returns: TRUE if open, FALSE if closing/closed
+ */
 gboolean vnc_display_is_open(VncDisplay *obj)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -1799,6 +1887,16 @@ gboolean vnc_display_is_open(VncDisplay *obj)
     return vnc_connection_is_open(priv->conn);
 }
 
+
+/**
+ * vnc_display_close:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Request that the connection to the remote display
+ * is closed. The actual close will complete asynchronously
+ * and the "vnc-disconnected" signal will be emitted once
+ * complete.
+ */
 void vnc_display_close(VncDisplay *obj)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -1818,6 +1916,15 @@ void vnc_display_close(VncDisplay *obj)
 }
 
 
+/**
+ * vnc_display_get_connection:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Get the VNC connection object associated with the
+ * display
+ *
+ * Returns: (transfer none): the connection object
+ */
 VncConnection * vnc_display_get_connection(VncDisplay *obj)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -1827,13 +1934,15 @@ VncConnection * vnc_display_get_connection(VncDisplay *obj)
 
 /**
  * vnc_display_send_keys:
- *
- * @obj: The #VncDisplay
+ * @obj: (transfer none): the VNC display widget
  * @keyvals: (array length=nkeyvals): Keyval array
  * @nkeyvals: Length of keyvals
  *
- * Send keyval click events to the display.
+ * Send keyval click events to the display. Al the
+ * key press events will be sent first and then all
+ * the key release events.
  *
+ * @keyvals should contain the X11 key value constants
  */
 void vnc_display_send_keys(VncDisplay *obj, const guint *keyvals, int nkeyvals)
 {
@@ -1858,6 +1967,23 @@ static guint get_scancode_from_keyval(VncDisplay *obj, guint keyval)
     return vnc_display_keymap_gdk2rfb(priv->keycode_map, priv->keycode_maplen, keycode);
 }
 
+
+/**
+ * vnc_display_send_keys_ex:
+ * @obj: (transfer none): the VNC display widget
+ * @keyvals: (array length=nkeyvals): Keyval array
+ * @nkeyvals: Length of keyvals
+ * @kind: the type of event to send
+ *
+ * Sends key events to the remote server. @keyvals
+ * should contain X11 key code values. These will
+ * be automatically converted to XT scancodes if
+ * needed
+ *
+ * If @kind is VNC_DISPLAY_KEY_EVENT_CLICK then all
+ * the key press events will be sent first, followed
+ * by all the key release events.
+ */
 void vnc_display_send_keys_ex(VncDisplay *obj, const guint *keyvals,
                               int nkeyvals, VncDisplayKeyEvent kind)
 {
@@ -1879,6 +2005,19 @@ void vnc_display_send_keys_ex(VncDisplay *obj, const guint *keyvals,
     }
 }
 
+
+/**
+ * vnc_display_send_pointer:
+ * @obj: (transfer none): the VNC display widget
+ * @x: the desired horizontal position
+ * @y: the desired vertical position
+ * @button_mask: the state of the buttons
+ *
+ * Move the remote pointer to position (@x, @y) and set the
+ * button state to @button_mask.  This method will only
+ * work if the desktop is using absolute pointer mode. It
+ * will be a no-op if in relative pointer mode.
+ */
 void vnc_display_send_pointer(VncDisplay *obj, gint x, gint y, int button_mask)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -2412,11 +2551,35 @@ static void vnc_display_init(VncDisplay *display)
     priv->keycode_map = vnc_display_keymap_gdk2rfb_table(&priv->keycode_maplen);
 }
 
+
+/**
+ * vnc_display_set_credential:
+ * @obj: (transfer none): the VNC display widget
+ * @type: the authentication credential type
+ * @data: (transfer none): the value associated with the credential
+ *
+ * Sets the value of the authentication credential
+ * @type to the string @data.
+ *
+ * @type is one of the VncConnectionCredential enum vlaues
+ *
+ * Returns: TRUE if an error occurs, FALSE otherwise
+ */
 gboolean vnc_display_set_credential(VncDisplay *obj, int type, const gchar *data)
 {
     return !vnc_connection_set_credential(obj->priv->conn, type, data);
 }
 
+
+/**
+ * vnc_display_set_poiter_local:
+ * @obj: (transfer none): the VNC display widget
+ * @enable: TRUE to show a local cursor, FALSE otherwise
+ *
+ * If @enable is TRUE, then a local mouse cursor will be
+ * made visible. If @enable is FALSE, the local mouse
+ * cursor will be hidden.
+ */
 void vnc_display_set_pointer_local(VncDisplay *obj, gboolean enable)
 {
     if (obj->priv->null_cursor) {
@@ -2428,6 +2591,15 @@ void vnc_display_set_pointer_local(VncDisplay *obj, gboolean enable)
     obj->priv->local_pointer = enable;
 }
 
+
+/**
+ * vnc_display_set_pointer_grab:
+ * @obj: (transfer none): the VNC display widget
+ * @enable: TRUE to enable automatic pointer grab, FALSE otherwise
+ *
+ * Set whether the widget will automatically grab the mouse
+ * pointer upon a button click
+ */
 void vnc_display_set_pointer_grab(VncDisplay *obj, gboolean enable)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -2440,10 +2612,11 @@ void vnc_display_set_pointer_grab(VncDisplay *obj, gboolean enable)
 
 /**
  * vnc_display_set_grab_keys:
- * @obj: (transfer none): the vnc display object
+ * @obj: (transfer none): the VNC display widget
  * @seq: (transfer none): the new grab sequence
  *
- * Set the key grab sequence
+ * Set the sequence of keys that must be pressed to
+ * activate keyborad and pointer grab
  */
 void vnc_display_set_grab_keys(VncDisplay *obj, VncGrabSequence *seq)
 {
@@ -2467,7 +2640,7 @@ void vnc_display_set_grab_keys(VncDisplay *obj, VncGrabSequence *seq)
 
 /**
  * vnc_display_get_grab_keys:
- * @obj: the vnc display object
+ * @obj: (transfer none): the VNC display widget
  *
  * Get the current grab key sequence
  *
@@ -2478,6 +2651,17 @@ VncGrabSequence *vnc_display_get_grab_keys(VncDisplay *obj)
     return obj->priv->vncgrabseq;
 }
 
+
+/**
+ * vnc_display_set_keyboard_grab:
+ * @obj: (transfer none): the VNC display widget
+ * @enable: TRUE to enable keyboard grab, FALSE otherwise
+ *
+ * Set whether the widget will grab the keyboard when it
+ * has focus. Grabbing the keyboard allows it to intercept
+ * special key sequences, ensuring they get sent to the
+ * remote desktop, rather than intepreted locally.
+ */
 void vnc_display_set_keyboard_grab(VncDisplay *obj, gboolean enable)
 {
     VncDisplayPrivate *priv = obj->priv;
@@ -2487,6 +2671,17 @@ void vnc_display_set_keyboard_grab(VncDisplay *obj, gboolean enable)
         do_keyboard_ungrab(obj, FALSE);
 }
 
+
+/**
+ * vnc_display_set_read_only:
+ * @obj: (transfer none): the VNC display widget
+ * @enable: TRUE to enable read-only mode, FALSE otherwise
+ *
+ * Set whether the widget is running in read-only mode. In
+ * read-only mode, keyboard and mouse events will not be
+ * sent to the remote desktop server. The widget will merely
+ * display activity from the server.
+ */
 void vnc_display_set_read_only(VncDisplay *obj, gboolean enable)
 {
     obj->priv->read_only = enable;
@@ -2518,7 +2713,7 @@ static void vnc_display_convert_data(GdkPixbuf *pixbuf,
 
 /**
  * vnc_display_get_pixbuf:
- * @obj: a #VncDisplay
+ * @obj: (transfer none): the VNC display widget
  *
  * Take a screenshot of the display.
  *
@@ -2556,6 +2751,16 @@ GdkPixbuf *vnc_display_get_pixbuf(VncDisplay *obj)
 }
 
 
+/**
+ * vnc_display_get_width:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Get the width of the remote desktop. This is only
+ * valid after the "vnc-initialized" signal has been
+ * emitted
+ *
+ * Returns: the remote desktop width
+ */
 int vnc_display_get_width(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), -1);
@@ -2563,6 +2768,17 @@ int vnc_display_get_width(VncDisplay *obj)
     return vnc_connection_get_width (obj->priv->conn);
 }
 
+
+/**
+ * vnc_display_get_height:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Get the height of the remote desktop. This is only
+ * valid after the "vnc-initialized" signal has been
+ * emitted
+ *
+ * Returns: the remote desktop height
+ */
 int vnc_display_get_height(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), -1);
@@ -2570,6 +2786,17 @@ int vnc_display_get_height(VncDisplay *obj)
     return vnc_connection_get_height (obj->priv->conn);
 }
 
+
+/**
+ * vnc_display_get_name:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Get the name of the remote desktop. This is only
+ * valid after the "vnc-initialized" signal has been
+ * emitted
+ *
+ * Returns: (transfer none): the remote desktop name
+ */
 const char * vnc_display_get_name(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), NULL);
@@ -2577,6 +2804,16 @@ const char * vnc_display_get_name(VncDisplay *obj)
     return vnc_connection_get_name (obj->priv->conn);
 }
 
+
+/**
+ * vnc_display_cut_text:
+ * @obj: (transfer none): the VNC display widget
+ * @text: (transfer none): the clipboard text
+ *
+ * Send a text string to the remote desktop clipboard. The
+ * encoding for @text is undefined, but it is recommended
+ * to use UTF-8.
+ */
 void vnc_display_client_cut_text(VncDisplay *obj, const gchar *text)
 {
     g_return_if_fail (VNC_IS_DISPLAY (obj));
@@ -2585,18 +2822,53 @@ void vnc_display_client_cut_text(VncDisplay *obj, const gchar *text)
         vnc_connection_client_cut_text(obj->priv->conn, text, strlen (text));
 }
 
+
+/**
+ * vnc_display_set_lossy_encoding:
+ * @obj: (transfer none): the VNC display widget
+ * @enable: TRUE to permit lossy encodings, FALSE otherwise
+ *
+ * Set whether the client is willing to accept lossy
+ * framebuffer update encodings. Lossy encodings can
+ * improve performance by lowering network bandwidth
+ * requirements, with a cost that the display received
+ * by the client will not be pixel perfect
+ */
 void vnc_display_set_lossy_encoding(VncDisplay *obj, gboolean enable)
 {
     g_return_if_fail (VNC_IS_DISPLAY (obj));
     obj->priv->allow_lossy = enable;
 }
 
+
+/**
+ * vnc_display_set_shared_flag:
+ * @obj: (transfer none): the VNC display widget
+ * @shared: the new sharing state
+ *
+ * Set the shared state for the connection. A TRUE value
+ * allow allow this client to co-exist with other existing
+ * clients. A FALSE value will cause other clients to be
+ * dropped
+ */
 void vnc_display_set_shared_flag(VncDisplay *obj, gboolean shared)
 {
     g_return_if_fail (VNC_IS_DISPLAY (obj));
     obj->priv->shared_flag = shared;
 }
 
+
+/**
+ * vnc_display_set_scaling:
+ * @obj: (transfer none): the VNC display widget
+ * @enable: TRUE to allow scaling the desktop to fit, FALSE otherwise
+ *
+ * Set whether the remote desktop contents is automatically
+ * scaled to fit the available widget size, or whether it
+ * will be rendered at 1:1 size
+ *
+ * Returns: TRUE always
+ */
 gboolean vnc_display_set_scaling(VncDisplay *obj,
                                  gboolean enable)
 {
@@ -2618,12 +2890,34 @@ gboolean vnc_display_set_scaling(VncDisplay *obj,
 }
 
 
+/**
+ * vnc_display_force_size:
+ * @obj: (transfer none): the VNC display widget
+ * @enabled: TRUE to force the widget size, FALSE otherwise
+ *
+ * Set whether the widget size will be forced to match the
+ * remote desktop size. If the widget size does not match
+ * the remote desktop size, and scaling is disabled, some
+ * of the remote desktop may be hidden, or black borders
+ * may be drawn.
+ */
 void vnc_display_set_force_size(VncDisplay *obj, gboolean enabled)
 {
     g_return_if_fail (VNC_IS_DISPLAY (obj));
     obj->priv->force_size = enabled;
 }
 
+
+/**
+ * vnc_display_set_depth:
+ * @obj: (transfer none): the VNC display widget
+ * @depth: the desired colour depth
+ *
+ * Set the desired colour depth. Higher quality colour
+ * depths will require greater network bandwidth. The
+ * colour depth must be set prior to connecting to the
+ * remote server
+ */
 void vnc_display_set_depth(VncDisplay *obj, VncDisplayDepthColor depth)
 {
     g_return_if_fail (VNC_IS_DISPLAY (obj));
@@ -2638,6 +2932,15 @@ void vnc_display_set_depth(VncDisplay *obj, VncDisplayDepthColor depth)
     obj->priv->depth = depth;
 }
 
+
+/**
+ * vnc_display_get_depth:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Get the desired colour depth
+ *
+ * Returns: the color depth
+ */
 VncDisplayDepthColor vnc_display_get_depth(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), 0);
@@ -2645,6 +2948,16 @@ VncDisplayDepthColor vnc_display_get_depth(VncDisplay *obj)
     return obj->priv->depth;
 }
 
+
+/**
+ * vnc_display_get_force_size:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine whether the widget size is being forced
+ * to match the desktop size
+ *
+ * Returns: TRUE if force size is enabled, FALSE otherwise
+ */
 gboolean vnc_display_get_force_size(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2652,6 +2965,17 @@ gboolean vnc_display_get_force_size(VncDisplay *obj)
     return obj->priv->force_size;
 }
 
+
+/**
+ * vnc_display_get_scaling:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine whether the widget is permitted to
+ * scale the remote desktop to fit the current
+ * widget size.
+ *
+ * Returns: TRUE if scaling is permitted, FALSE otherwise
+ */
 gboolean vnc_display_get_scaling(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2659,6 +2983,16 @@ gboolean vnc_display_get_scaling(VncDisplay *obj)
     return obj->priv->allow_scaling;
 }
 
+
+/**
+ * vnc_display_get_lossy_encoding:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine whether lossy framebuffer update encodings
+ * are permitted
+ *
+ * Returns: TRUE if lossy encodings are permitted, FALSE otherwie
+ */
 gboolean vnc_display_get_lossy_encoding(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2666,6 +3000,16 @@ gboolean vnc_display_get_lossy_encoding(VncDisplay *obj)
     return obj->priv->allow_lossy;
 }
 
+
+/**
+ * vnc_display_get_shared_flag:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine if other clients are permitted to
+ * share the VNC connection
+ *
+ * Returns: TRUE if sharing is permittted, FALSE otherwise
+ */
 gboolean vnc_display_get_shared_flag(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2673,6 +3017,15 @@ gboolean vnc_display_get_shared_flag(VncDisplay *obj)
     return obj->priv->shared_flag;
 }
 
+
+/**
+ * vnc_display_get_pointer_local:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine if a local pointer will be shown
+ *
+ * Returns: TRUE if a local pointer is shown, FALSE otherwise
+ */
 gboolean vnc_display_get_pointer_local(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2680,6 +3033,16 @@ gboolean vnc_display_get_pointer_local(VncDisplay *obj)
     return obj->priv->local_pointer;
 }
 
+
+/**
+ * vnc_display_get_pointer_grab:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine if the mouse pointer will be grabbed
+ * on first click
+ *
+ * Returns: TRUE if the pointer will be grabbed, FALSE otherwise
+ */
 gboolean vnc_display_get_pointer_grab(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2687,6 +3050,16 @@ gboolean vnc_display_get_pointer_grab(VncDisplay *obj)
     return obj->priv->grab_pointer;
 }
 
+
+/**
+ * vnc_display_get_keyboard_grab:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine if the keyboard will be grabbed when the
+ * widget has input focus.
+ *
+ * Returns: TRUE if the keyboard will be grabbed, FALSE otherwise
+ */
 gboolean vnc_display_get_keyboard_grab(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2694,6 +3067,16 @@ gboolean vnc_display_get_keyboard_grab(VncDisplay *obj)
     return obj->priv->grab_keyboard;
 }
 
+
+/**
+ * vnc_display_get_read_only:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine if the widget will operate in read-only
+ * mode, denying keyboard/mouse inputs
+ *
+ * Returns: TRUE if in read-only mode, FALSE otherwise
+ */
 gboolean vnc_display_get_read_only(VncDisplay *obj)
 {
     g_return_val_if_fail (VNC_IS_DISPLAY (obj), FALSE);
@@ -2701,11 +3084,31 @@ gboolean vnc_display_get_read_only(VncDisplay *obj)
     return obj->priv->read_only;
 }
 
+
+/**
+ * vnc_display_is_pointer_absolute:
+ * @obj: (transfer none): the VNC display widget
+ *
+ * Determine if the pointer is operating in absolute
+ * mode. This is only valid after the "vnc-initialized"
+ * signal has been emitted
+ *
+ * Returns: TRUE if in absolute mode, FALSE for relative mode
+ */
 gboolean vnc_display_is_pointer_absolute(VncDisplay *obj)
 {
     return obj->priv->absolute;
 }
 
+
+/**
+ * vnc_display_get_option_group:
+ *
+ * Get a command line option group containing VNC specific
+ * options.
+ *
+ * Returns: (transfer full): the option group
+ */
 GOptionGroup *
 vnc_display_get_option_group (void)
 {
@@ -2719,12 +3122,26 @@ vnc_display_get_option_group (void)
     return group;
 }
 
+
+/**
+ * vnc_display_get_option_entries:
+ *
+ * Get the array of command line option entries containing
+ * VNC specific otions
+ *
+ * Returns: (array zero-terminated=1): the option entries
+ */
 const GOptionEntry *
 vnc_display_get_option_entries (void)
 {
     return gtk_vnc_args;
 }
 
+
+/**
+ * vnc_display_:
+ * @obj: (transfer none): the VNC display widget
+ */
 gboolean
 vnc_display_request_update(VncDisplay *obj)
 {
diff --git a/src/vncframebuffer.c b/src/vncframebuffer.c
index 9f021b2..548d163 100644
--- a/src/vncframebuffer.c
+++ b/src/vncframebuffer.c
@@ -23,42 +23,109 @@
 
 #include "vncframebuffer.h"
 
-
+/**
+ * vnc_framebuffer_get_width:
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Query the width of the remote framebuffer
+ *
+ * Returns: the framebuffer width
+ */
 guint16 vnc_framebuffer_get_width(VncFramebuffer *fb)
 {
     return VNC_FRAMEBUFFER_GET_INTERFACE(fb)->get_width(fb);
 }
 
+/**
+ * vnc_framebuffer_get_height:
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Query the height of the remote framebuffer
+ *
+ * Returns: the frambuffer height
+ */
 guint16 vnc_framebuffer_get_height(VncFramebuffer *fb)
 {
     return VNC_FRAMEBUFFER_GET_INTERFACE(fb)->get_height(fb);
 }
 
+/**
+ * vnc_framebuffer_get_rowstride:
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Get the number of bytes per line of the framebuffer
+ *
+ * Returns: the framebuffer row stride
+ */
 int vnc_framebuffer_get_rowstride(VncFramebuffer *fb)
 {
     return VNC_FRAMEBUFFER_GET_INTERFACE(fb)->get_rowstride(fb);
 }
 
+/**
+ * vnc_framebuffer_get_buffer:
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Get a pointer to the framebuffer contents
+ *
+ * Returns: (transfer none)(array): the framebuffer data
+ */
 guint8 *vnc_framebuffer_get_buffer(VncFramebuffer *fb)
 {
     return VNC_FRAMEBUFFER_GET_INTERFACE(fb)->get_buffer(fb);
 }
 
+/**
+ * vnc_framebuffer_get_local_format:
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Get the pixel format used to store the framebuffer locally
+ *
+ * Returns: (transfer none): the local pixel format
+ */
 const VncPixelFormat *vnc_framebuffer_get_local_format(VncFramebuffer *fb)
 {
     return VNC_FRAMEBUFFER_GET_INTERFACE(fb)->get_local_format(fb);
 }
 
+/**
+ * vnc_framebuffer_remote_format:
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Get the pixel format used by the remote desktop sending
+ * framebuffer updates.
+ *
+ * Returns: (transfer none): the remote pixel format
+ */
 const VncPixelFormat *vnc_framebuffer_get_remote_format(VncFramebuffer *fb)
 {
     return VNC_FRAMEBUFFER_GET_INTERFACE(fb)->get_remote_format(fb);
 }
 
+/**
+ * vnc_framebuffer_perfect_format_match:
+ * @fb: (transfer none): the framebuffer object
+ *
+ * Determine if the local and remote pixel formats match
+ *
+ * Returns: TRUE if the local and remote pixel formats match
+ */
 gboolean vnc_framebuffer_perfect_format_match(VncFramebuffer *fb)
 {
     return VNC_FRAMEBUFFER_GET_INTERFACE(fb)->perfect_format_match(fb);
 }
 
+/**
+ * vnc_framebuffer_set_pixel_at:
+ * @fb: (transfer none): the framebuffer object
+ * @src: (array)(transfer none): the new pixel data
+ * @x: the horizontal pixel to set
+ * @y: the vertical pixel to set
+ *
+ * Sets a pixel in the framebuffer at (@x, @y) to the
+ * value in @src. The number of bytes in @src is
+ * determined by the remote pixel format
+ */
 void vnc_framebuffer_set_pixel_at(VncFramebuffer *fb,
                                   guint8 *src,
                                   guint16 x, guint16 y)
@@ -66,6 +133,20 @@ void vnc_framebuffer_set_pixel_at(VncFramebuffer *fb,
     VNC_FRAMEBUFFER_GET_INTERFACE(fb)->set_pixel_at(fb, src, x, y);
 }
 
+/**
+ * vnc_framebuffer_fill:
+ * @fb: (transfer none): the framebuffer object
+ * @src: (array)(transfer none): the new pixel data
+ * @x: the horizontal pixel to start filling
+ * @y: the vertical pixel to start filling
+ * @width: the number of pixels to fill horizontally
+ * @height: the number of pixels to fill vertically
+ *
+ * Fill all the pixels in the range (@x, @y) to
+ * (@x + @width, @y + @height) to the value in
+ * @src. The number of bytes in @src is
+ * determined by the remote pixel format
+ */
 void vnc_framebuffer_fill(VncFramebuffer *fb,
                           guint8 *src,
                           guint16 x, guint16 y,
@@ -74,6 +155,20 @@ void vnc_framebuffer_fill(VncFramebuffer *fb,
     VNC_FRAMEBUFFER_GET_INTERFACE(fb)->fill(fb, src, x, y, width, height);
 }
 
+/**
+ * vnc_framebuffer_copyrect:
+ * @fb: (transfer none): the framebuffer object
+ * @srcx: the horizontal starting pixel
+ * @srcy: the vertical starting pixel
+ * @dstx: the horizontal target pixel
+ * @dsty: the vertical target pixel
+ * @width: the width of the region
+ * @height: the height of the region
+ *
+ * Copies data from the range (@srcx, @srcy) to
+ * (@srcx+@width, @srcy+@height) over to the
+ * range starting at (@dstx, @dsty).
+ */
 void vnc_framebuffer_copyrect(VncFramebuffer *fb,
                               guint16 srcx, guint16 srcy,
                               guint16 dstx, guint16 dsty,
@@ -82,6 +177,21 @@ void vnc_framebuffer_copyrect(VncFramebuffer *fb,
     VNC_FRAMEBUFFER_GET_INTERFACE(fb)->copyrect(fb, srcx, srcy, dstx, dsty, width, height);
 }
 
+/**
+ * vnc_framebuffer_:
+ * @fb: (transfer none): the framebuffer object
+ * @src: (array)(transfer none): the new pixel data
+ * @rowstride: the number of bytes per row
+ * @x: the horizontal pixel to start filling
+ * @y: the vertical pixel to start filling
+ * @width: the number of pixels to fill horizontally
+ * @height: the number of pixels to fill vertically
+ *
+ * Fill all the pixels in the range (@x, @y) to
+ * (@x + @width, @y + @height) to the value in
+ * @src. The number of bytes in @src is
+ * determined by the remote pixel format
+ */
 void vnc_framebuffer_blt(VncFramebuffer *fb,
                          guint8 *src,
                          int rowstride,
@@ -91,6 +201,21 @@ void vnc_framebuffer_blt(VncFramebuffer *fb,
     VNC_FRAMEBUFFER_GET_INTERFACE(fb)->blt(fb, src, rowstride, x, y, width, height);
 }
 
+/**
+ * vnc_framebuffer_rgb24_blt:
+ * @fb: (transfer none): the framebuffer object
+ * @src: (array)(transfer none): the new pixel data
+ * @rowstride: the number of bytes per row
+ * @x: the horizontal pixel to start filling
+ * @y: the vertical pixel to start filling
+ * @width: the number of pixels to fill horizontally
+ * @height: the number of pixels to fill vertically
+ *
+ * Fill all the pixels in the range (@x, @y) to
+ * (@x + @width, @y + @height) to the value in
+ * @src. The number of bytes in @src is always
+ * 3 as it must be in plain RGB24 format.
+ */
 void vnc_framebuffer_rgb24_blt(VncFramebuffer *fb,
                                guint8 *src,
                                int rowstride,
@@ -101,6 +226,13 @@ void vnc_framebuffer_rgb24_blt(VncFramebuffer *fb,
 }
 
 
+/**
+ * vnc_framebuffer_set_color_map:
+ * @fb: (transfer none): the framebuffer object
+ * @map: (transfer none): the new color map
+ *
+ * Set the color map to use for the framebuffer
+ */
 void vnc_framebuffer_set_color_map(VncFramebuffer *fb,
                                    VncColorMap *map)
 {
diff --git a/src/vncgrabsequence.c b/src/vncgrabsequence.c
index 5cb4b84..072e2d9 100644
--- a/src/vncgrabsequence.c
+++ b/src/vncgrabsequence.c
@@ -44,7 +44,7 @@ GType vnc_grab_sequence_get_type(void)
 /**
  * vnc_grab_sequence_new:
  * @nkeysyms: length of @keysyms
- * @keysyms: (array length=nkeysyms): the keysym values
+ * @keysyms: (transfer none)(array length=nkeysyms): the keysym values
  *
  * Creates a new grab sequence from a list of keysym values
  *
@@ -65,10 +65,13 @@ VncGrabSequence *vnc_grab_sequence_new(guint nkeysyms, guint *keysyms)
 
 /**
  * vnc_grab_sequence_new_from_string:
- * @str: string of keysym names
+ * @str: (transfer none): string of keysym names
  *
  * Creates a new grab sequence from a list of keysym names
  *
+ * The returned struct must be freed by calling
+ * vnc_grab_sequence_free when no longer required
+ *
  * Returns: (transfer full): a new grab sequence object
  */
 VncGrabSequence *vnc_grab_sequence_new_from_string(const gchar *str)
@@ -97,19 +100,38 @@ VncGrabSequence *vnc_grab_sequence_new_from_string(const gchar *str)
 }
 
 
-VncGrabSequence *vnc_grab_sequence_copy(VncGrabSequence *srcSequence)
+/**
+ * vnc_grab_sequence_copy:
+ * @sequence: (transfer none): the grab sequence
+ *
+ * Allocate a new grab sequence struct, initalizing it
+ * with a copy of data  from @sequence
+ *
+ * The returned struct must be freed by calling
+ * vnc_grab_sequence_free when no longer required
+ *
+ * Returns: (transfer full): the grab sequence
+ */
+VncGrabSequence *vnc_grab_sequence_copy(VncGrabSequence *sequence)
 {
-    VncGrabSequence *sequence;
+    VncGrabSequence *ret;
 
-    sequence = g_slice_dup(VncGrabSequence, srcSequence);
-    sequence->keysyms = g_new0(guint, srcSequence->nkeysyms);
-    memcpy(sequence->keysyms, srcSequence->keysyms,
-           sizeof(guint) * sequence->nkeysyms);
+    ret = g_slice_dup(VncGrabSequence, sequence);
+    ret->keysyms = g_new0(guint, sequence->nkeysyms);
+    memcpy(ret->keysyms, sequence->keysyms,
+           sizeof(guint) * ret->nkeysyms);
 
-    return sequence;
+    return ret;
 }
 
 
+/**
+ * vnc_grab_sequence_free:
+ * @sequence: (transfer none): the grab sequence
+ *
+ * Release memory associated with the grab sequence
+ * @sequence.
+ */
 void vnc_grab_sequence_free(VncGrabSequence *sequence)
 {
     g_slice_free(VncGrabSequence, sequence);
@@ -142,7 +164,7 @@ gchar *vnc_grab_sequence_as_string(VncGrabSequence *sequence)
 /**
  * vnc_grab_sequence_get_nth:
  * @sequence: (transfer none): the grab sequence
- * @nth: the index of the key symbol to obtain
+ * @n: the index of the key symbol to obtain
  *
  * Obtain the nth key symbol in the sequence
  *
diff --git a/src/vncimageframebuffer.c b/src/vncimageframebuffer.c
index a012409..2bb7401 100644
--- a/src/vncimageframebuffer.c
+++ b/src/vncimageframebuffer.c
@@ -129,6 +129,16 @@ void vnc_image_framebuffer_init(VncImageFramebuffer *fb)
 }
 
 
+/**
+ * vnc_image_framebuffer_new:
+ * @image: (transfer none): the image to render into
+ * @remoteFormat: (transfer none): the remote pixel format
+ *
+ * Allocate a new framebuffer that renders the remote
+ * desktop into the image object @image
+ *
+ * Returns: (transfer full): the new framebuffer
+ */
 VncImageFramebuffer *vnc_image_framebuffer_new(GdkImage *image,
                                                const VncPixelFormat *remoteFormat)
 {
@@ -199,6 +209,14 @@ VncImageFramebuffer *vnc_image_framebuffer_new(GdkImage *image,
 }
 
 
+/**
+ * vnc_image_framebuffer_get_image:
+ * @fb: the framebuffer object
+ *
+ * Get the image to which the remote desktop is being rendered
+ *
+ * Returns: (transfer none): the image object
+ */
 GdkImage *vnc_image_framebuffer_get_image(VncImageFramebuffer *fb)
 {
     VncImageFramebufferPrivate *priv = fb->priv;
diff --git a/src/vncpixelformat.c b/src/vncpixelformat.c
index 06c825c..e8fbe3b 100644
--- a/src/vncpixelformat.c
+++ b/src/vncpixelformat.c
@@ -37,6 +37,16 @@ GType vnc_pixel_format_get_type(void)
 }
 
 
+/**
+ * vnc_pixel_format_new:
+ *
+ * Allocate a new VNC pixel format struct whose
+ * contents is initialized to all zeros. The
+ * struct must be released using vnc_pixel_format_free
+ * when no longer required
+ *
+ * Returns: (transfer full): the new pixel format struct
+ */
 VncPixelFormat *vnc_pixel_format_new(void)
 {
     VncPixelFormat *format;
@@ -46,7 +56,17 @@ VncPixelFormat *vnc_pixel_format_new(void)
     return format;
 }
 
-
+/**
+ * vnc_pixel_format_copy:
+ * @srcFormat: the format to copy
+ *
+ * Allocate a new VNC pixel format struct whose
+ * contents is initialized with the data found
+ * in @srcFormat. The struct must be released using
+ * vnc_pixel_format_free when no longer required.
+ *
+ * Returns: (transfer full): the new pixel format struct
+ */
 VncPixelFormat *vnc_pixel_format_copy(VncPixelFormat *srcFormat)
 {
     VncPixelFormat *format;
@@ -57,6 +77,12 @@ VncPixelFormat *vnc_pixel_format_copy(VncPixelFormat *srcFormat)
 }
 
 
+/**
+ * vnc_pixel_format_free:
+ * @format: the format to free
+ *
+ * Release the memory associated with @format
+ */
 void vnc_pixel_format_free(VncPixelFormat *format)
 {
     g_slice_free(VncPixelFormat, format);
diff --git a/src/vncutil.c b/src/vncutil.c
index 7af8365..3197f97 100644
--- a/src/vncutil.c
+++ b/src/vncutil.c
@@ -28,6 +28,13 @@
 
 static gboolean debugFlag = FALSE;
 
+/**
+ * vnc_util_set_debug:
+ * @enabled: TRUE to turn on verbose debugging
+ *
+ * Control whether the VNC code emits verbose debug
+ * messages on stderr
+ */
 void vnc_util_set_debug(gboolean enabled)
 {
 #if GLIB_CHECK_VERSION(2, 31, 0)
@@ -45,11 +52,29 @@ void vnc_util_set_debug(gboolean enabled)
     debugFlag = enabled;
 }
 
+
+/**
+ * vnc_util_get_debug:
+ *
+ * Determine whether the VNC code will emit verbose
+ * debug messages
+ *
+ * Returns: TRUE if debugging is enabled, FALSE otherwise
+ */
 gboolean vnc_util_get_debug(void)
 {
     return debugFlag;
 }
 
+/**
+ * vnc_util_get_version:
+ *
+ * Get the encoded version number of the library release.
+ * The major, minor and micro components are encoded in
+ * 8-bits each.
+ *
+ * Returns: the library version number
+ */
 gint vnc_util_get_version(void)
 {
     return (VERSION_MAJOR << 16) |
@@ -57,6 +82,18 @@ gint vnc_util_get_version(void)
         VERSION_MICRO;
 }
 
+
+/**
+ * vnc_util_check_version:
+ * @major: the desired major version
+ * @minor: the desired minor version
+ * @micro: the desired micro version
+ *
+ * Check whether the library is at least as new as the
+ * version (@major, @minor, @micro)
+ *
+ * Returns: TRUE if the library is at least as new as the requested version
+ */
 gboolean vnc_util_check_version(gint major, gint minor, gint micro)
 {
     return ((VERSION_MAJOR > major) || \
@@ -65,6 +102,15 @@ gboolean vnc_util_check_version(gint major, gint minor, gint micro)
              (VERSION_MICRO >= micro)));
 }
 
+
+/**
+ * vnc_util_get_version_string:
+ *
+ * Get the library version number in a printable
+ * string format
+ *
+ * Returns: (transfer none): the version string
+ */
 const gchar *vnc_util_get_version_string(void)
 {
     return VERSION;