2002-09-05 nalin first pass at writing documentation fix

2002-09-05 nalin
	* docs/reference: first pass at writing documentation
	* src/termcap.c: fix how'd-that-ever-work in vte_termcap_strip(), patch
	from Brian Cameron.  Take \\e as an alias for \\E, which is already
	an alias for Escape.
	* src/vte.c(vte_terminal_get_cursor): Return an absolute cursor position
	instead of a relative position.

15 files changed, 830 insertions, 114 deletions

diff --git a/src/caps.c b/src/caps.c
index d3632f1..a2d9de2 100644
--- a/src/caps.c
+++ b/src/caps.c
@@ -527,6 +527,16 @@ struct vte_capability_string vte_xterm_capability_strings[] = {
 	{NULL, NULL, 0},
 };
 
+/**
+ * vte_capability_init:
+ *
+ * Initializes the vte_terminal_capability_strings and
+ * vte_xterm_capability_strings structures used by the terminal.  Can
+ * be called multiple times without ill effect.
+ *
+ * Returns: void
+ */
+
 void
 vte_capability_init(void)
 {
diff --git a/src/caps.h b/src/caps.h
index 5bfe422..ac99693 100644
--- a/src/caps.h
+++ b/src/caps.h
@@ -25,12 +25,12 @@
 
 G_BEGIN_DECLS
 
-#define VTE_CAP_ESC ""
-#define VTE_CAP_CSI VTE_CAP_ESC "["
-#define VTE_CAP_ST  VTE_CAP_ESC "\\"
-#define VTE_CAP_OSC VTE_CAP_ESC "]"
-#define VTE_CAP_PM  VTE_CAP_ESC "^"
-#define VTE_CAP_APC VTE_CAP_ESC "_"
+#define VTE_CAP_ESC "\033"		/* Escape */
+#define VTE_CAP_CSI VTE_CAP_ESC "["	/* Control Sequence Introducer */
+#define VTE_CAP_ST  VTE_CAP_ESC "\\"	/* String Terminator */
+#define VTE_CAP_OSC VTE_CAP_ESC "]"	/* Operating System Command */
+#define VTE_CAP_PM  VTE_CAP_ESC "^"	/* Privacy Message */
+#define VTE_CAP_APC VTE_CAP_ESC "_"	/* Application Program Command */
 
 /* A NULL-terminated list of capability strings which have string values,
  * which means they're either key sequences or commands. */
diff --git a/src/debug.h b/src/debug.h
index b84844d..a748378 100644
--- a/src/debug.h
+++ b/src/debug.h
@@ -33,7 +33,7 @@ typedef enum {
 	VTE_DEBUG_SELECTION	= 1 << 6,
 	VTE_DEBUG_SUBSTITUTION	= 1 << 7,
 	VTE_DEBUG_RING		= 1 << 8,
-	VTE_DEBUG_PTY		= 1 << 9,
+	VTE_DEBUG_PTY		= 1 << 9
 } VteDebugFlags;
 
 void vte_debug_parse_string(const char *string);
diff --git a/src/iso2022.h b/src/iso2022.h
index 18ab84c..10f4441 100644
--- a/src/iso2022.h
+++ b/src/iso2022.h
@@ -27,7 +27,6 @@
 
 G_BEGIN_DECLS
 
-struct vte_iso2022;
 struct vte_iso2022 *vte_iso2022_new(void);
 struct vte_iso2022 *vte_iso2022_copy(struct vte_iso2022 *original);
 void vte_iso2022_free(struct vte_iso2022 *p);
diff --git a/src/pty.c b/src/pty.c
index ecf8bb6..233b374 100644
--- a/src/pty.c
+++ b/src/pty.c
@@ -152,6 +152,17 @@ vte_pty_fork_on_pty(const char *path, char **env_add,
 	_exit(0);
 }
 
+/**
+ * vte_pty_set_size:
+ * @master: the file descriptor of the pty master
+ * @columns: the desired number of columns
+ * @rows: the desired number of rows
+ *
+ * Attempts to resize the pseudo terminal's window size.  If successful, the
+ * OS kernel will send #SIGWINCH to the child process group.
+ *
+ * Returns: 0 on success, -1 on failure.
+ */
 int
 vte_pty_set_size(int master, int columns, int rows)
 {
@@ -178,6 +189,16 @@ vte_pty_set_size(int master, int columns, int rows)
 	return ret;
 }
 
+/**
+ * vte_pty_get_size:
+ * @master: the file descriptor of the pty master
+ * @columns: a place to store the number of columns
+ * @rows: a place to store the number of rows
+ *
+ * Attempts to read the pseudo terminal's window size.
+ *
+ * Returns: 0 on success, -1 on failure.
+ */
 int
 vte_pty_get_size(int master, int *columns, int *rows)
 {
@@ -330,6 +351,21 @@ vte_pty_open_old_school(pid_t *child, char **env_add,
 	return -1;
 }
 
+/**
+ * vte_pty_open:
+ * @child: location to store the new process's ID
+ * @env_add: a list of environment variables to add to the child's environment
+ * @command: name of the binary to run
+ * @argv: arguments to pass to @command
+ * @columns: desired window columns
+ * @rows: desired window rows
+ *
+ * Starts a new copy of @command running under a psuedo-terminal, with window
+ * size set to @rows x @columns and variables in @env_add added to its
+ * environment.
+ *
+ * Returns: an open file descriptor for the pty master, -1 on failure
+ */
 int
 vte_pty_open(pid_t *child, char **env_add,
 	     const char *command, char **argv,
diff --git a/src/reaper.c b/src/reaper.c
index 46a1488..c440d66 100644
--- a/src/reaper.c
+++ b/src/reaper.c
@@ -163,6 +163,11 @@ vte_reaper_get_type(void)
 	return reaper_type;
 }
 
+/**
+ * vte_reaper_get:
+ *
+ * Returns: the global #VteReaper object
+ */
 VteReaper *
 vte_reaper_get(void)
 {
diff --git a/src/ring.c b/src/ring.c
index 6a70635..d624e84 100644
--- a/src/ring.c
+++ b/src/ring.c
@@ -37,8 +37,20 @@ vte_ring_validate(VteRing *ring)
 }
 #endif
 
+/**
+ * vte_ring_new:
+ * @max_elements: the maximum size the new ring will be allowed to reach
+ * @free: a #VteRingFreeFunc
+ * @data: user data for @free
+ *
+ * Allocates a new ring capable of holding up to @max_elements elements at a
+ * time, using @free to free them when they are removed from the ring.  The
+ * @data pointer is passed to the @free callback whenever it is called.
+ *
+ * Returns: a new ring
+ */
 VteRing *
-vte_ring_new(long max_elements, VteRingFreeFunc free, gpointer data)
+vte_ring_new(glong max_elements, VteRingFreeFunc free, gpointer data)
 {
 	VteRing *ret = g_malloc0(sizeof(VteRing));
 	ret->user_data = data;
@@ -50,7 +62,7 @@ vte_ring_new(long max_elements, VteRingFreeFunc free, gpointer data)
 }
 
 VteRing *
-vte_ring_new_with_delta(long max_elements, long delta,
+vte_ring_new_with_delta(glong max_elements, glong delta,
 			VteRingFreeFunc free, gpointer data)
 {
 	VteRing *ret;
@@ -59,6 +71,17 @@ vte_ring_new_with_delta(long max_elements, long delta,
 	return ret;
 }
 
+/**
+ * vte_ring_insert:
+ * @ring: a #VteRing
+ * @position: an index
+ * @data: the new item
+ *
+ * Inserts a new item (@data) into @ring at the @position'th offset.  If @ring
+ * already has an item stored at the desired location, it will be freed before
+ * being replaced by the new @data.
+ *
+ */
 void
 vte_ring_insert(VteRing *ring, long position, gpointer data)
 {
@@ -145,6 +168,16 @@ vte_ring_insert(VteRing *ring, long position, gpointer data)
 #endif
 }
 
+/**
+ * vte_ring_remove:
+ * @ring: a #VteRing
+ * @position: an index
+ * @free_element: TRUE if the item should be freed
+ *
+ * Removes the @position'th item from @ring, freeing it only if @free_element is
+ * TRUE.
+ *
+ */
 void
 vte_ring_remove(VteRing *ring, long position, gboolean free)
 {
@@ -186,17 +219,34 @@ vte_ring_remove(VteRing *ring, long position, gboolean free)
 #endif
 }
 
+/**
+ * vte_ring_append:
+ * @ring: a #VteRing
+ * @data: the new item
+ *
+ * Appends a new item to the ring.  If an item must be removed to make room for
+ * the new item, it is freed.
+ *
+ */
 void
 vte_ring_append(VteRing *ring, gpointer data)
 {
 	vte_ring_insert(ring, ring->delta + ring->length, data);
 }
 
+/**
+ * vte_ring_free:
+ * @ring: a #VteRing
+ * @free_elements: TRUE if items in the ring should be freed
+ *
+ * Frees the ring and, optionally, each of the items it contains.
+ *
+ */
 void
-vte_ring_free(VteRing *ring, gboolean free)
+vte_ring_free(VteRing *ring, gboolean free_elements)
 {
 	long i;
-	if (free) {
+	if (free_elements) {
 		for (i = 0; i < ring->max; i++) {
 			/* Remove this item. */
 			if ((ring->free != NULL) && (ring->array[i] != NULL)) {
diff --git a/src/ring.h b/src/ring.h
index 9a968a3..f992722 100644
--- a/src/ring.h
+++ b/src/ring.h
@@ -32,7 +32,7 @@ struct _VteRing {
 	VteRingFreeFunc free;
 	gpointer user_data;
 	gpointer *array;
-	long delta, length, max;
+	glong delta, length, max;
 };
 
 #define vte_ring_contains(__ring, __position) \
@@ -54,11 +54,13 @@ struct _VteRing {
 #define vte_ring_index(__ring, __cast, __position) \
 	(__cast) vte_ring_at(__ring, __position)
 
-VteRing *vte_ring_new(long max_elements, VteRingFreeFunc free, gpointer data);
-VteRing *vte_ring_new_with_delta(long max_elements, long delta,
+VteRing *vte_ring_new(glong max_elements,
+		      VteRingFreeFunc free,
+		      gpointer data);
+VteRing *vte_ring_new_with_delta(glong max_elements, glong delta,
 				 VteRingFreeFunc free, gpointer data);
-void vte_ring_insert(VteRing *ring, long position, gpointer data);
-void vte_ring_remove(VteRing *ring, long position, gboolean free_element);
+void vte_ring_insert(VteRing *ring, glong position, gpointer data);
+void vte_ring_remove(VteRing *ring, glong position, gboolean free_element);
 void vte_ring_append(VteRing *ring, gpointer data);
 void vte_ring_free(VteRing *ring, gboolean free_elements);
 
diff --git a/src/table.c b/src/table.c
index e08ac8b..1698dbe 100644
--- a/src/table.c
+++ b/src/table.c
@@ -60,7 +60,7 @@ struct vte_table {
 enum vte_table_argtype {
 	vte_table_arg_number,
 	vte_table_arg_string,
-	vte_table_arg_char,
+	vte_table_arg_char
 };
 struct vte_table_arginfo {
 	enum vte_table_argtype type;
diff --git a/src/termcap.c b/src/termcap.c
index 5ae93d5..4f8e15a 100644
--- a/src/termcap.c
+++ b/src/termcap.c
@@ -223,6 +223,7 @@ vte_termcap_strip_with_pad(const char *termcap, char **stripped, gssize *len)
 					}
 					continue;
 				case 'E':
+				case 'e':
 					i++;
 					ret[o - 1] = 27;
 					continue;
@@ -306,11 +307,22 @@ vte_termcap_strip_with_pad(const char *termcap, char **stripped, gssize *len)
 	*len = o;
 }
 
+/**
+ * vte_termcap_strip:
+ * @termcap: a termcap structure
+ * @stripped: a location to store the new stripped version of the string
+ * @len: a location to store the length of the new string
+ *
+ * Converts various types of sequences used to represent non-printable data
+ * into the data they represent.  Specifically, this resolves ^{char} sequences,
+ * octal escapes. and the \r, \n, \E, \t, \b, and \f sequences.
+ *
+ */
 void
 vte_termcap_strip(const char *termcap, char **stripped, gssize *len)
 {
 	vte_termcap_strip_with_pad(termcap, stripped, len);
-	while ((len > 0) && ((*stripped)[(*len) - 1] == ':')) {
+	while (((*len) > 0) && ((*stripped)[(*len) - 1] == ':')) {
 		(*len)--;
 		(*stripped)[*len] = '\0';
 	}
@@ -380,6 +392,13 @@ vte_termcap_new(const char *filename)
 	return ret;
 }
 
+/**
+ * vte_termcap_free:
+ * @termcap: the structure to be freed
+ *
+ * Frees the indicated structure.
+ *
+ */
 TERMCAP_MAYBE_STATIC void
 vte_termcap_free(struct vte_termcap *termcap)
 {
@@ -512,6 +531,17 @@ vte_termcap_find(struct vte_termcap *termcap,
 	return vte_termcap_find_l(termcap, tname, strlen(tname), cap);
 }
 
+/**
+ * vte_termcap_find_boolean:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ *
+ * Checks if the given boolean capability is defined.
+ *
+ * Returns: TRUE if the terminal type is known and the capability is defined
+ * for it
+ */
 TERMCAP_MAYBE_STATIC gboolean
 vte_termcap_find_boolean(struct vte_termcap *termcap, const char *tname,
 			 const char *cap)
@@ -525,6 +555,17 @@ vte_termcap_find_boolean(struct vte_termcap *termcap, const char *tname,
 	return FALSE;
 }
 
+/**
+ * vte_termcap_find_numeric:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ *
+ * Checks if the given numeric capability is defined.
+ *
+ * Returns: non-zero if the terminal type is known and the capability is defined
+ * to a non-zero value for it
+ */
 TERMCAP_MAYBE_STATIC long
 vte_termcap_find_numeric(struct vte_termcap *termcap, const char *tname,
 			 const char *cap)
@@ -545,6 +586,18 @@ vte_termcap_find_numeric(struct vte_termcap *termcap, const char *tname,
 	return 0;
 }
 
+/**
+ * vte_termcap_find_string:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ *
+ * Checks if the given string capability is defined.
+ *
+ * Returns: the value of the capability if the terminal type is known and the
+ * capability is defined for it, else an empty string.  The return value must
+ * always be freed by the caller.
+ */
 TERMCAP_MAYBE_STATIC char *
 vte_termcap_find_string(struct vte_termcap *termcap, const char *tname,
 			const char *cap)
@@ -565,6 +618,20 @@ vte_termcap_find_string(struct vte_termcap *termcap, const char *tname,
 	return g_strdup("");
 }
 
+/**
+ * vte_termcap_find_string_length:
+ * @termcap: a termcap structure
+ * @tname: the name of the terminal type being queried
+ * @cap: the name of the capability being queried
+ * @length: the location to store the length of the returned string
+ *
+ * Checks if the given string capability is defined.  This version of
+ * vte_termcap_find_string() properly handles zero bytes in the result.
+ *
+ * Returns: the value of the capability if the terminal type is known and the
+ * capability is defined for it, else an empty string.  The return value must
+ * always be freed by the caller.
+ */
 TERMCAP_MAYBE_STATIC char *
 vte_termcap_find_string_length(struct vte_termcap *termcap, const char *tname,
 			       const char *cap, ssize_t *length)
@@ -578,7 +645,10 @@ vte_termcap_find_string_length(struct vte_termcap *termcap, const char *tname,
 		val += (l + 1);
 		p = val;
 		while (*p != ':') p++;
-		*length = l = p - val;
+		l = p - val;
+		if (length) {
+			*length = l;
+		}
 		ret = g_malloc(l + 1);
 		if (l > 0) {
 			memcpy(ret, val, l);
diff --git a/src/trie.c b/src/trie.c
index 5bd41cd..4919867 100644
--- a/src/trie.c
+++ b/src/trie.c
@@ -61,7 +61,7 @@ struct char_class {
 		multi,			/* Multiple-number special class. */
 		any,			/* Any single character. */
 		string,			/* Any string of characters. */
-		invalid,		/* A placeholder. */
+		invalid			/* A placeholder. */
 	} type;
 	gboolean multiple;		/* Whether a sequence of multiple
 					   characters in this class should be
diff --git a/src/vte.c b/src/vte.c
index 8431116..85bf465 100644
--- a/src/vte.c
+++ b/src/vte.c
@@ -147,13 +147,13 @@ struct vte_draw_item {
  * are really only defined for "application" mode. */
 typedef enum _VteKeypad {
 	VTE_KEYPAD_NORMAL,
-	VTE_KEYPAD_APPLICATION,
+	VTE_KEYPAD_APPLICATION
 } VteKeypad;
 
 /* The terminal's function key setting. */
 typedef enum _VteFKey {
 	VTE_FKEY_VT220,
-	VTE_FKEY_SUNPC,
+	VTE_FKEY_SUNPC
 } VteFKey;
 
 typedef struct _VteScreen VteScreen;
@@ -245,7 +245,7 @@ struct _VteTerminalPrivate {
 	enum {
 		selection_type_char,
 		selection_type_word,
-		selection_type_line,
+		selection_type_line
 	} selection_type;
 	struct selection_event_coords {
 		double x, y;
@@ -623,7 +623,7 @@ vte_invalidate_all(VteTerminal *terminal)
 /* Scroll a rectangular region up or down by a fixed number of lines. */
 static void
 vte_terminal_scroll_region(VteTerminal *terminal,
-			   long row, long count, long delta)
+			   long row, glong count, glong delta)
 {
 	GtkWidget *widget;
 	gboolean repaint = TRUE;
@@ -654,7 +654,7 @@ vte_terminal_scroll_region(VteTerminal *terminal,
 
 /* Find the character in the given "virtual" position. */
 static struct vte_charcell *
-vte_terminal_find_charcell(VteTerminal *terminal, long col, long row)
+vte_terminal_find_charcell(VteTerminal *terminal, glong col, glong row)
 {
 	GArray *rowdata;
 	struct vte_charcell *ret = NULL;
@@ -1101,7 +1101,7 @@ vte_terminal_match_contents_clear(VteTerminal *terminal)
 
 /* Refresh the cache of the screen contents we keep. */
 static gboolean
-always_selected(VteTerminal *terminal, long row, long column)
+always_selected(VteTerminal *terminal, glong row, glong column)
 {
 	return TRUE;
 }
@@ -1118,7 +1118,14 @@ vte_terminal_match_contents_refresh(VteTerminal *terminal)
 	terminal->pvt->match_attributes = array;
 }
 
-/* Display string matching:  clear all matching expressions. */
+/**
+ * vte_terminal_match_clear_all:
+ * @terminal: a #VteTerminal
+ *
+ * Clears the list of regular expressions the terminal uses to highlight text
+ * when the user moves the mouse cursor.
+ * 
+ */
 void
 vte_terminal_match_clear_all(VteTerminal *terminal)
 {
@@ -1137,8 +1144,17 @@ vte_terminal_match_clear_all(VteTerminal *terminal)
 	vte_terminal_match_hilite_clear(terminal);
 }
 
-/* Add a matching expression, returning the tag the widget assigns to that
- * expression. */
+/**
+ * vte_terminal_match_add:
+ * @terminal: a #VteTerminal
+ * @match: a regular expression
+ *
+ * Adds a regular expression to the list of matching expressions.  When the
+ * user moves the mouse cursor over a section of displayed text which matches
+ * this expression, the text will be highlighted.
+ * 
+ * Returns: an integer associated with this expression
+ */
 int
 vte_terminal_match_add(VteTerminal *terminal, const char *match)
 {
@@ -1162,7 +1178,7 @@ vte_terminal_match_add(VteTerminal *terminal, const char *match)
  * argument. */
 static char *
 vte_terminal_match_check_internal(VteTerminal *terminal,
-				  long column, long row,
+				  long column, glong row,
 				  int *tag, int *start, int *end)
 {
 	int i, j, ret, offset;
@@ -1301,8 +1317,28 @@ vte_terminal_match_check_internal(VteTerminal *terminal,
 	return NULL;
 }
 
+/**
+ * vte_terminal_match_check:
+ * @terminal: a #VteTerminal
+ * @column: the text column
+ * @row: the text row
+ * @tag: pointer to an integer
+ *
+ * Checks if the text in and around the specified position matches any of the
+ * regular expressions previously set using vte_terminal_match_add().  If a
+ * match exists, the text string is returned and if @tag is not NULL, the number
+ * associated with the matched regular expression will be stored in @tag.
+ * 
+ * If more than one regular expression has been set with
+ * vte_terminal_match_add(), then expressions are checked in the order in
+ * which they were added.
+ * 
+ * Returns: a string which matches one of the previously set regular
+ * expressions, and which must be freed by the caller.
+ */
 char *
-vte_terminal_match_check(VteTerminal *terminal, long column, long row, int *tag)
+vte_terminal_match_check(VteTerminal *terminal, glong column, glong row,
+			 int *tag)
 {
 	long delta;
 	char *ret;
@@ -1542,7 +1578,7 @@ vte_sequence_handler_multiple(VteTerminal *terminal,
 
 /* Insert a blank line at an arbitrary position. */
 static void
-vte_insert_line_internal(VteTerminal *terminal, long position)
+vte_insert_line_internal(VteTerminal *terminal, glong position)
 {
 	GArray *array;
 	/* Pad out the line data to the insertion point. */
@@ -1562,7 +1598,7 @@ vte_insert_line_internal(VteTerminal *terminal, long position)
 
 /* Remove a line at an arbitrary position. */
 static void
-vte_remove_line_internal(VteTerminal *terminal, long position)
+vte_remove_line_internal(VteTerminal *terminal, glong position)
 {
 	if (vte_ring_next(terminal->pvt->screen->row_data) > position) {
 		vte_ring_remove(terminal->pvt->screen->row_data,
@@ -1570,8 +1606,17 @@ vte_remove_line_internal(VteTerminal *terminal, long position)
 	}
 }
 
-/* Change the encoding used for the terminal to the given codeset, or the
- * locale default if NULL is passed in. */
+/**
+ * vte_terminal_set_encoding:
+ * @terminal: a #VteTerminal
+ * @codeset: a valid #gconv target
+ *
+ * Changes the encoding the terminal will expect data from the child to
+ * be encoded with.  For certain terminal types, applications executing in the
+ * terminal can change the encoding.  The default encoding is defined by the
+ * application's locale settings.
+ *
+ */
 void
 vte_terminal_set_encoding(VteTerminal *terminal, const char *codeset)
 {
@@ -1708,6 +1753,16 @@ vte_terminal_set_encoding(VteTerminal *terminal, const char *codeset)
 #endif
 	vte_terminal_emit_encoding_changed(terminal);
 }
+
+/**
+ * vte_terminal_get_encoding:
+ * @terminal: a #VteTerminal
+ *
+ * Determines the name of the encoding in which the terminal expects data to be
+ * encoded.
+ *
+ * Returns: the current encoding for the terminal.
+ */
 const char *
 vte_terminal_get_encoding(VteTerminal *terminal)
 {
@@ -5245,9 +5300,13 @@ static struct {
 	{"window-manipulation", vte_sequence_handler_window_manipulation},
 };
 
-/* Create the basic widget.  This more or less creates and initializes a
- * GtkWidget and clears out the rest of the data which is specific to our
- * widget class. */
+/**
+ * vte_terminal_new:
+ *
+ * Create a new terminal widget.
+ *
+ * Returns: a new #VteTerminal object
+ */
 GtkWidget *
 vte_terminal_new(void)
 {
@@ -5387,14 +5446,28 @@ vte_terminal_generate_bold(const struct vte_palette_entry *foreground,
 #endif
 }
 
-/* Set the bold foreground color. */
+/**
+ * vte_terminal_set_color_bold
+ * @terminal: a #VteTerminal
+ * @bold: the new bold color
+ *
+ * Sets the color used to draw bold text in the default foreground color.
+ *
+ */
 void
 vte_terminal_set_color_bold(VteTerminal *terminal, const GdkColor *bold)
 {
 	vte_terminal_set_color_internal(terminal, VTE_BOLD_FG, bold);
 }
 
-/* Set the foreground color. */
+/**
+ * vte_terminal_set_color_foreground
+ * @terminal: a #VteTerminal
+ * @foreground: the new foreground color
+ *
+ * Sets the foreground color used to draw normal text
+ *
+ */
 void
 vte_terminal_set_color_foreground(VteTerminal *terminal,
 				  const GdkColor *foreground)
@@ -5402,7 +5475,16 @@ vte_terminal_set_color_foreground(VteTerminal *terminal,
 	vte_terminal_set_color_internal(terminal, VTE_DEF_FG, foreground);
 }
 
-/* Set the background color. */
+/**
+ * vte_terminal_set_color_background
+ * @terminal: a #VteTerminal
+ * @background: the new background color
+ *
+ * Sets the background color for text which does not have a specific background
+ * color assigned.  Only has effect when no background image is set and when
+ * the terminal is not transparent.
+ *
+ */
 void
 vte_terminal_set_color_background(VteTerminal *terminal,
 				  const GdkColor *background)
@@ -5410,7 +5492,26 @@ vte_terminal_set_color_background(VteTerminal *terminal,
 	vte_terminal_set_color_internal(terminal, VTE_DEF_BG, background);
 }
 
-/* Set a given set of colors as the palette. */
+/**
+ * vte_terminal_set_colors
+ * @terminal: a #VteTerminal
+ * @foreground: the new foreground color, or #NULL
+ * @background: the new background color, or #NULL
+ * @palette: the color palette
+ * @palette_size: the number of entries in @palette
+ *
+ * The terminal widget uses a 19-color model comprised of the default foreground
+ * and background colors, the bold foreground color, an eight color palette, and
+ * bold versions of the eight color palette.
+ *
+ * @palette_size must be either 0, 8, or 16.  If @foreground is NULL and
+ * @palette_size is greater than 0, the new foreground color is taken from
+ * @palette[7].  If @background is NULL and @palette_size is greater than 0,
+ * the new background color is taken from @palette[0].  If @palette_size is
+ * 8, the second 8-color palette is extrapolated from the new background
+ * color and the items in @palette.
+ *
+ */
 void
 vte_terminal_set_colors(VteTerminal *terminal,
 			const GdkColor *foreground,
@@ -5515,7 +5616,13 @@ vte_terminal_set_colors(VteTerminal *terminal,
 	terminal->pvt->palette_initialized = TRUE;
 }
 
-/* Reset palette defaults for character colors. */
+/**
+ * vte_terminal_set_default_colors:
+ * @terminal: a #VteTerminal
+ *
+ * Reset the terminal palette to reasonable compiled-in defaults.
+ *
+ */
 void
 vte_terminal_set_default_colors(VteTerminal *terminal)
 {
@@ -5793,7 +5900,20 @@ vte_terminal_catch_child_exited(VteReaper *reaper, int pid, int status,
 	}
 }
 
-/* Start up a command in a slave PTY. */
+/**
+ * vte_terminal_fork_command:
+ * @terminal: a #VteTerminal
+ * @command: the name of a binary to run
+ * @argv: the argument list to be passed to @command
+ * @envv: a list of environment variables to be added to the environment before
+ * starting @command
+ *
+ * Starts the specified command under a newly-alllocated control
+ * pseudo-terminal.  TERM is automatically set to reflect the terminal widget's
+ * emulation setting.
+ *
+ * Returns: the ID of the new process
+ */
 pid_t
 vte_terminal_fork_command(VteTerminal *terminal, const char *command,
 			  char **argv, char **envv)
@@ -6365,13 +6485,28 @@ vte_terminal_io_read(GIOChannel *channel,
 	return leave_open;
 }
 
-/* Render some UTF-8 text. */
+/**
+ * vte_terminal_feed:
+ * @terminal: a #VteTerminal
+ * @data: a string
+ * @length: the length of the string
+ *
+ * Interprets @data as if it were data received from a child process.  This
+ * can either be used to drive the terminal without a child process, or just
+ * to mess with your users.
+ *
+ */
 void
 vte_terminal_feed(VteTerminal *terminal, const char *data, glong length)
 {
 	char *buf;
 	gboolean empty;
 
+	/* If length == -1, use the length of the data string. */
+	if (length == ((gssize)-1)) {
+		length = strlen(data);
+	}
+
 	/* Allocate space for old and new data. */
 	buf = g_malloc(terminal->pvt->n_incoming + length + 1);
 	empty = (terminal->pvt->n_incoming == 0);
@@ -6519,17 +6654,26 @@ vte_terminal_send(VteTerminal *terminal, const char *encoding,
 	return;
 }
 
-/* Send a chunk of UTF-8 text to the child. */
+/**
+ * vte_terminal_feed_child:
+ * @terminal: a #VteTerminal
+ * @data: data to send to the child
+ * @length: length of @text
+ *
+ * Sends a block of UTF-8 text to the child as if it were entered by the user
+ * at the keyboard.
+ *
+ */
 void
-vte_terminal_feed_child(VteTerminal *terminal, const char *text, glong length)
+vte_terminal_feed_child(VteTerminal *terminal, const char *data, glong length)
 {
 	g_return_if_fail(VTE_IS_TERMINAL(terminal));
 	if (length == ((gssize)-1)) {
-		length = strlen(text);
+		length = strlen(data);
 	}
 	vte_terminal_im_reset(terminal);
 	if (length > 0) {
-		vte_terminal_send(terminal, "UTF-8", text, length);
+		vte_terminal_send(terminal, "UTF-8", data, length);
 	}
 }
 
@@ -7151,7 +7295,16 @@ vte_terminal_key_release(GtkWidget *widget, GdkEventKey *event)
 	return gtk_im_context_filter_keypress(terminal->pvt->im_context, event);
 }
 
-/* Check if a particular character is part of a "word" or not. */
+/**
+ * vte_terminal_is_word_char:
+ * @terminal: a #VteTerminal
+ * @c: a candidate Unicode code point
+ *
+ * Checks if a particular character is considered to be part of a word or not,
+ * based on the values last passed to vte_terminal_set_word_chars().
+ * 
+ * Returns: TRUE if the character is considered to be part of a word
+ */
 gboolean
 vte_terminal_is_word_char(VteTerminal *terminal, gunichar c)
 {
@@ -7175,7 +7328,7 @@ vte_terminal_is_word_char(VteTerminal *terminal, gunichar c)
 /* Check if the characters in the given block are in the same class (word vs.
  * non-word characters). */
 static gboolean
-vte_uniform_class(VteTerminal *terminal, long row, long scol, long ecol)
+vte_uniform_class(VteTerminal *terminal, glong row, glong scol, glong ecol)
 {
 	struct vte_charcell *pcell = NULL;
 	long col;
@@ -7199,8 +7352,8 @@ vte_uniform_class(VteTerminal *terminal, long row, long scol, long ecol)
 }
 
 static gboolean
-vte_cell_is_between(long col, long row,
-		    long acol, long arow, long bcol, long brow,
+vte_cell_is_between(glong col, glong row,
+		    glong acol, glong arow, glong bcol, glong brow,
 		    gboolean inclusive)
 {
 	long t;
@@ -7262,7 +7415,7 @@ vte_cell_is_between(long col, long row,
 
 /* Check if a cell is selected or not. */
 static gboolean
-vte_cell_is_selected(VteTerminal *terminal, long col, long row)
+vte_cell_is_selected(VteTerminal *terminal, glong col, glong row)
 {
 	long scol, ecol;
 
@@ -7959,12 +8112,31 @@ vte_terminal_copy_cb(GtkClipboard *clipboard, GtkSelectionData *data,
 	}
 }
 
-/* Extract a view of the widget as if we were going to copy it. */
+/**
+ * vte_terminal_get_text_range:
+ * @terminal: a #VteTerminal
+ * @start_row: first row to search for data
+ * @start_col: first column to search for data
+ * @end_row: last row to search for data
+ * @end_col: last column to search for data
+ * @is_selected: a callback
+ * @attributes: location for storing text attributes
+ *
+ * Extracts a view of the visible part of the string.  If @is_selected is not
+ * NULL, characters will only be read if @is_selected returns TRUE after being
+ * passed the column and row, respectively.  A #vte_char_attributes structure
+ * is added to @attributes for each byte added to the returned string detailing
+ * the character&apos;s position, colors, and other characteristics.  The
+ * entire scrollback buffer is scanned, so it is possible to read the entire
+ * contents of the buffer using this function.
+ *
+ * Returns: a text string which must be freed by the caller.
+ */
 char *
 vte_terminal_get_text_range(VteTerminal *terminal,
 			    glong start_row, glong start_col,
 			    glong end_row, glong end_col,
-			    gboolean(*is_selected)(VteTerminal *, long, long),
+			    gboolean(*is_selected)(VteTerminal *, glong, glong),
 			    GArray *attributes)
 {
 	long col, row, spaces;
@@ -8063,10 +8235,23 @@ vte_terminal_get_text_range(VteTerminal *terminal,
 	return g_string_free(string, FALSE);
 }
 
-/* Extract a view of the widget as if we were going to copy it. */
+/**
+ * vte_terminal_get_text:
+ * @terminal: a #VteTerminal
+ * @is_selected: a callback
+ * @attributes: location for storing text attributes
+ *
+ * Extracts a view of the visible part of the string.  If @is_selected is not
+ * NULL, characters will only be read if @is_selected returns TRUE after being
+ * passed the column and row, respectively.  A #vte_char_attributes structure
+ * is added to @attributes for each byte added to the returned string detailing
+ * the character&apos;s position, colors, and other characteristics.
+ *
+ * Returns: a text string which must be freed by the caller.
+ */
 char *
 vte_terminal_get_text(VteTerminal *terminal,
-		      gboolean(*is_selected)(VteTerminal *, long, long),
+		      gboolean(*is_selected)(VteTerminal *, glong, glong),
 		      GArray *attributes)
 {
 	long start_row, start_col, end_row, end_col;
@@ -8077,19 +8262,32 @@ vte_terminal_get_text(VteTerminal *terminal,
 	return vte_terminal_get_text_range(terminal,
 					   start_row, start_col,
 					   end_row, end_col,
-					   is_selected,
+					   is_selected ?
+					   is_selected : always_selected,
 					   attributes);
 }
 
-/* Tell the caller where the cursor is, in screen coordinates. */
+/**
+ * vte_terminal_get_cursor_position:
+ * @terminal: a #VteTerminal
+ * @column: long which will hold the column 
+ * @row : long which will hold the row
+ *
+ * Reads the location of the insertion cursor and returns it.  The row
+ * coordinate is absolute.
+ *
+ */
 void
 vte_terminal_get_cursor_position(VteTerminal *terminal,
-				 long *column, long *row)
+				 glong *column, glong *row)
 {
 	g_return_if_fail(VTE_IS_TERMINAL(terminal));
-	*column = terminal->pvt->screen->cursor_current.col;
-	*row    = terminal->pvt->screen->cursor_current.row -
-		  terminal->pvt->screen->insert_delta;
+	if (column) {
+		*column = terminal->pvt->screen->cursor_current.col;
+	}
+	if (row) {
+		*row = terminal->pvt->screen->cursor_current.row;
+	}
 }
 
 /* Place the selected text onto the clipboard.  Do this asynchronously so that
@@ -8318,7 +8516,7 @@ vte_terminal_button_press(GtkWidget *widget, GdkEventButton *event)
 				fprintf(stderr, "Handling click ourselves.\n");
 			}
 #endif
-			vte_terminal_paste(terminal, GDK_SELECTION_PRIMARY);
+			vte_terminal_paste_primary(terminal);
 			ret = TRUE;
 		}
 	} else
@@ -9301,7 +9499,18 @@ vte_terminal_close_font(VteTerminal *terminal)
 #endif
 }
 
-/* Set the fontset used for rendering text into the widget. */
+/**
+ * vte_terminal_set_font:
+ * @terminal: a #VteTerminal
+ * @font_desc: The #PangoFontDescription of the desired font.
+ *
+ * Sets the font used for rendering all text displayed by the terminal,
+ * overriding any fonts set using gtk_widget_modify_font().  The terminal
+ * will immediately attempt to load the desired font, retrieve its
+ * metrics, and attempts to resize itself to keep the same number of rows
+ * and columns.
+ *
+ */
 void
 vte_terminal_set_font(VteTerminal *terminal,
 		      const PangoFontDescription *font_desc)
@@ -9357,6 +9566,15 @@ vte_terminal_set_font(VteTerminal *terminal,
 	vte_terminal_open_font(terminal);
 }
 
+/**
+ * vte_terminal_set_font_from_string:
+ * @terminal: a #VteTerminal
+ * @name: A string describing the font.
+ *
+ * A convenience function which converts @name into a #PangoFontDescription and
+ * passes it to vte_terminal_set_font().
+ *
+ */
 void
 vte_terminal_set_font_from_string(VteTerminal *terminal, const char *name)
 {
@@ -9370,6 +9588,13 @@ vte_terminal_set_font_from_string(VteTerminal *terminal, const char *name)
 	pango_font_description_free(font_desc);
 }
 
+/**
+ * vte_terminal_get_font:
+ * @terminal: a #VteTerminal
+ *
+ * Returns: a #PangoFontDescription describing the font the terminal is
+ * currently using to render text.
+ */
 const PangoFontDescription *
 vte_terminal_get_font(VteTerminal *terminal)
 {
@@ -9395,9 +9620,18 @@ vte_terminal_refresh_size(VteTerminal *terminal)
 	}
 }
 
-/* Set the size of the PTY. */
+/**
+ * vte_terminal_set_size:
+ * @terminal: a #VteTerminal
+ * @columns: the desired number of columns
+ * @rows: the desired number of rows
+ *
+ * Attempts to change the terminal's size in terms of rows and columns.  If
+ * the attempt succeeds, the widget will resize itself to the proper size.
+ *
+ */
 void
-vte_terminal_set_size(VteTerminal *terminal, long columns, long rows)
+vte_terminal_set_size(VteTerminal *terminal, glong columns, glong rows)
 {
 	struct winsize size;
 	g_return_if_fail(VTE_IS_TERMINAL(terminal));
@@ -9483,7 +9717,16 @@ vte_terminal_set_scroll_adjustment(VteTerminal *terminal,
 	}
 }
 
-/* Set the type of terminal we're emulating. */
+/**
+ * vte_terminal_set_emulation:
+ * @terminal: a #VteTerminal
+ * @emulation: the name of a terminal description
+ *
+ * Sets what type of terminal the widget attempts to emulate by scanning for
+ * control sequences defined in the system's termcap file.  Unless you
+ * are interested in this feature, always use "xterm".
+ *
+ */
 void
 vte_terminal_set_emulation(VteTerminal *terminal, const char *emulation)
 {
@@ -9619,6 +9862,12 @@ vte_terminal_set_emulation(VteTerminal *terminal, const char *emulation)
 	vte_terminal_emit_emulation_changed(terminal);
 }
 
+/**
+ * vte_terminal_get_emulation:
+ * @terminal: a #VteTerminal
+ *
+ * Returns: the name of the terminal type the widget is attempting to emulate
+ */
 const char *
 vte_terminal_get_emulation(VteTerminal *terminal)
 {
@@ -9667,7 +9916,7 @@ vte_terminal_set_termcap(VteTerminal *terminal, const char *path,
 }
 
 static void
-vte_terminal_reset_rowdata(VteRing **ring, long lines)
+vte_terminal_reset_rowdata(VteRing **ring, glong lines)
 {
 	VteRing *new_ring;
 	GArray *row;
@@ -12519,13 +12768,31 @@ vte_terminal_get_type(void)
 	return terminal_type;
 }
 
-/* External access functions. */
+/**
+ * vte_terminal_set_audible_bell:
+ * @terminal: a #VteTerminal
+ * @is_audible: TRUE if the terminal should beep
+ *
+ * Controls whether or not the terminal will beep when the child outputs the
+ * "bl" sequence.
+ *
+ */
 void
-vte_terminal_set_audible_bell(VteTerminal *terminal, gboolean audible)
+vte_terminal_set_audible_bell(VteTerminal *terminal, gboolean is_audible)
 {
 	g_return_if_fail(VTE_IS_TERMINAL(terminal));
-	terminal->pvt->audible_bell = audible;
+	terminal->pvt->audible_bell = is_audible;
 }
+
+/**
+ * vte_terminal_get_audible_bell:
+ * @terminal: a #VteTerminal
+ *
+ * Checks whether or not the terminal will beep when the child outputs the
+ * "bl" sequence.
+ *
+ * Returns: TRUE if audible bell is enabled, FALSE if not
+ */
 gboolean
 vte_terminal_get_audible_bell(VteTerminal *terminal)
 {
@@ -12533,12 +12800,33 @@ vte_terminal_get_audible_bell(VteTerminal *terminal)
 	return terminal->pvt->audible_bell;
 }
 
+/**
+ * vte_terminal_set_visible_bell:
+ * @terminal: a #VteTerminal
+ * @is_visible: TRUE if the terminal should flash
+ *
+ * Controls whether or not the terminal will present a visible bell to the
+ * user when the child outputs the "bl" sequence.  The terminal
+ * will clear itself to the default foreground color and then repaint itself.
+ *
+ */
 void
-vte_terminal_set_visible_bell(VteTerminal *terminal, gboolean visible)
+vte_terminal_set_visible_bell(VteTerminal *terminal, gboolean is_visible)
 {
 	g_return_if_fail(VTE_IS_TERMINAL(terminal));
-	terminal->pvt->visible_bell = visible;
+	terminal->pvt->visible_bell = is_visible;
 }
+
+/**
+ * vte_terminal_get_visible_bell:
+ * @terminal: a #VteTerminal
+ *
+ * Checks whether or not the terminal will present a visible bell to the
+ * user when the child outputs the "bl" sequence.  The terminal
+ * will clear itself to the default foreground color and then repaint itself.
+ *
+ * Returns: TRUE if visible bell is enabled, FALSE if not
+ */
 gboolean
 vte_terminal_get_visible_bell(VteTerminal *terminal)
 {
@@ -12546,6 +12834,15 @@ vte_terminal_get_visible_bell(VteTerminal *terminal)
 	return terminal->pvt->visible_bell;
 }
 
+/**
+ * vte_terminal_set_scroll_on_output:
+ * @terminal: a #VteTerminal
+ * @scroll: TRUE if the terminal should scroll on output
+ *
+ * Controls whether or not the terminal will forcibly scroll to the bottom of
+ * the viewable history when the new data is received from the child.
+ *
+ */
 void
 vte_terminal_set_scroll_on_output(VteTerminal *terminal, gboolean scroll)
 {
@@ -12553,6 +12850,16 @@ vte_terminal_set_scroll_on_output(VteTerminal *terminal, gboolean scroll)
 	terminal->pvt->scroll_on_output = scroll;
 }
 
+/**
+ * vte_terminal_set_scroll_on_keystroke:
+ * @terminal: a #VteTerminal
+ * @scroll: TRUE if the terminal should scroll on keystrokes
+ *
+ * Controls whether or not the terminal will forcibly scroll to the bottom of
+ * the viewable history when the user presses a key.  Modifier keys do not
+ * trigger this behavior.
+ *
+ */
 void
 vte_terminal_set_scroll_on_keystroke(VteTerminal *terminal, gboolean scroll)
 {
@@ -12560,6 +12867,14 @@ vte_terminal_set_scroll_on_keystroke(VteTerminal *terminal, gboolean scroll)
 	terminal->pvt->scroll_on_keystroke = scroll;
 }
 
+/**
+ * vte_terminal_copy_clipboard:
+ * @terminal: a #VteTerminal
+ *
+ * Places the selected text in the terminal in the #GDK_SELECTION_CLIPBOARD
+ * selection.
+ *
+ */
 void
 vte_terminal_copy_clipboard(VteTerminal *terminal)
 {
@@ -12567,6 +12882,15 @@ vte_terminal_copy_clipboard(VteTerminal *terminal)
 	vte_terminal_copy(terminal, GDK_SELECTION_CLIPBOARD);
 }
 
+/**
+ * vte_terminal_paste_clipboard:
+ * @terminal: a #VteTerminal
+ *
+ * Sends the contents of the #GDK_SELECTION_CLIPBOARD selection to the
+ * terminal's child.  If necessary, the data is converted from UTF-8 to the
+ * terminal's current encoding.
+ *
+ */
 void
 vte_terminal_paste_clipboard(VteTerminal *terminal)
 {
@@ -12574,6 +12898,14 @@ vte_terminal_paste_clipboard(VteTerminal *terminal)
 	vte_terminal_paste(terminal, GDK_SELECTION_CLIPBOARD);
 }
 
+/**
+ * vte_terminal_copy_primary:
+ * @terminal: a #VteTerminal
+ *
+ * Places the selected text in the terminal in the #GDK_SELECTION_PRIMARY
+ * selection.
+ *
+ */
 void
 vte_terminal_copy_primary(VteTerminal *terminal)
 {
@@ -12581,6 +12913,17 @@ vte_terminal_copy_primary(VteTerminal *terminal)
 	vte_terminal_copy(terminal, GDK_SELECTION_PRIMARY);
 }
 
+/**
+ * vte_terminal_paste_primary:
+ * @terminal: a #VteTerminal
+ *
+ * Sends the contents of the #GDK_SELECTION_PRIMARY selection to the terminal's
+ * child.  If necessary, the data is converted from UTF-8 to the terminal's
+ * current encoding.  The terminal will call also paste the
+ * #GDK_SELECTION_PRIMARY selection when the user clicks with the the second
+ * mouse button.
+ *
+ */
 void
 vte_terminal_paste_primary(VteTerminal *terminal)
 {
@@ -12588,7 +12931,16 @@ vte_terminal_paste_primary(VteTerminal *terminal)
 	vte_terminal_paste(terminal, GDK_SELECTION_PRIMARY);
 }
 
-/* Append the menu items for our input method context to the given shell. */
+/**
+ * vte_terminal_im_append_menuitems:
+ * @terminal: a #VteTerminal
+ * @menushell: a GtkMenuShell
+ *
+ * Appends menu items for various input methods to the given menu.  The
+ * user can select one of these items to modify the input method used by
+ * the terminal.
+ *
+ */
 void
 vte_terminal_im_append_menuitems(VteTerminal *terminal, GtkMenuShell *menushell)
 {
@@ -12836,6 +13188,24 @@ vte_terminal_setup_background(VteTerminal *terminal,
 	vte_invalidate_all(terminal);
 }
 
+/**
+ * vte_terminal_set_background_saturation:
+ * @terminal: a #VteTerminal
+ * @saturation: TRUE if the terminal should fake transparency
+ *
+ * If a background image has been set using
+ * vte_terminal_set_background_image(), 
+ * vte_terminal_set_background_image_file(), or
+ * vte_terminal_set_background_transparent(), the terminal will adjust the
+ * brightness of the image before drawing the image.  To do so, the terminal
+ * will create a copy of the background image (or snapshot of the root
+ * window) and modify its pixel values.
+ * 
+ * If your application intends to create multiple terminal widgets with the
+ * same settings, performing this step yourself and just using
+ * vte_terminal_set_background_image() will save memory.
+ * 
+ */
 void
 vte_terminal_set_background_saturation(VteTerminal *terminal, double saturation)
 {
@@ -12947,9 +13317,19 @@ vte_terminal_filter_property_changes(GdkXEvent *xevent, GdkEvent *event,
 	return GDK_FILTER_CONTINUE;
 }
 
-/* Turn background "transparency" on or off. */
+/**
+ * vte_terminal_set_background_transparent:
+ * @terminal: a #VteTerminal
+ * @transparent: TRUE if the terminal should fake transparency
+ *
+ * Sets the terminal's background image to the pixmap stored in the root
+ * window, adjusted so that if there are no windows below your application,
+ * the widget will appear to be transparent.
+ * 
+ */
 void
-vte_terminal_set_background_transparent(VteTerminal *terminal, gboolean setting)
+vte_terminal_set_background_transparent(VteTerminal *terminal,
+					gboolean transparent)
 {
 	GdkWindow *window;
 	GdkAtom atom;
@@ -12958,17 +13338,17 @@ vte_terminal_set_background_transparent(VteTerminal *terminal, gboolean setting)
 #ifdef VTE_DEBUG
 	if (vte_debug_on(VTE_DEBUG_MISC)) {
 		fprintf(stderr, "Turning background transparency %s.\n",
-			setting ? "on" : "off");
+			transparent ? "on" : "off");
 	}
 #endif
-	terminal->pvt->bg_transparent = setting;
+	terminal->pvt->bg_transparent = transparent;
 
 	/* To be "transparent", we treat the _XROOTPMAP_ID attribute of the
 	 * root window as a picture of what's beneath us, and use that as
 	 * the background.  It's a little tricky because we need to "scroll"
 	 * the image to match our window position. */
 	window = gdk_get_default_root_window();
-	if (setting) {
+	if (transparent) {
 		/* Get the window and property name we'll be watching for
 		 * changes in. */
 		atom = gdk_atom_intern("_XROOTPMAP_ID", TRUE);
@@ -12996,6 +13376,17 @@ vte_terminal_set_background_transparent(VteTerminal *terminal, gboolean setting)
 	vte_terminal_queue_background_update(terminal);
 }
 
+/**
+ * vte_terminal_set_background_image:
+ * @terminal: a #VteTerminal
+ * @image: a #GdkPixbuf to use, or #NULL to cancel
+ *
+ * Sets a background image for the widget.  Text which would otherwise be
+ * drawn using the default background color will instead be drawn over the
+ * specified image.  If necessary, the image will be tiled to cover the
+ * widget's entire visible area.
+ * 
+ */
 void
 vte_terminal_set_background_image(VteTerminal *terminal, GdkPixbuf *image)
 {
@@ -13029,9 +13420,21 @@ vte_terminal_set_background_image(VteTerminal *terminal, GdkPixbuf *image)
 	vte_terminal_queue_background_update(terminal);
 }
 
-/* Set the background image using just a file.  It's more efficient for a
- * caller to pass us an already-desaturated pixbuf if we've got multiple
- * instances going, but this is handy for the single-widget case. */
+/**
+ * vte_terminal_set_background_image_file:
+ * @terminal: a #VteTerminal
+ * @path: path to an image file
+ *
+ * Sets a background image for the widget.  If specified by
+ * vte_terminal_set_background_saturation, the terminal will make its
+ * in-memory copy of the image darker for its own use.
+ * 
+ * This is a convenience function for vte_terminal_set_background_image().
+ * If your application intends to create multiple terminal widgets using the
+ * same background, performing this step yourself and just using
+ * vte_terminal_set_background_image() will reduce memory consumption.
+ *
+ */
 void
 vte_terminal_set_background_image_file(VteTerminal *terminal, const char *path)
 {
@@ -13057,7 +13460,12 @@ vte_terminal_set_background_image_file(VteTerminal *terminal, const char *path)
 	}
 }
 
-/* Check if we're the current owner of the clipboard. */
+/**
+ * vte_terminal_get_has_selection:
+ * @terminal: a #VteTerminal
+ *
+ * Returns: TRUE if part of the text in the terminal is selected.
+ */
 gboolean
 vte_terminal_get_has_selection(VteTerminal *terminal)
 {
@@ -13065,7 +13473,18 @@ vte_terminal_get_has_selection(VteTerminal *terminal)
 	return terminal->pvt->has_selection;
 }
 
-/* Tell the caller if we're [planning on] using Xft for rendering. */
+/**
+ * vte_terminal_get_using_xft:
+ * @terminal: a #VteTerminal
+ *
+ * A #VteTerminal can use Xft, Pango, or Xlib to draw text.  This function
+ * allows an application to determine which mode the widget is in.  This
+ * setting cannot be changed by the caller, but in practice usually matches
+ * the behavior of GTK+ itself.
+ *
+ * Returns: TRUE if the terminal is using Xft to render, FALSE if the terminal
+ * is using Pango or Xlib.
+ */
 gboolean
 vte_terminal_get_using_xft(VteTerminal *terminal)
 {
@@ -13074,7 +13493,15 @@ vte_terminal_get_using_xft(VteTerminal *terminal)
 	       (terminal->pvt->render_method == VteRenderXft1);
 }
 
-/* Toggle the cursor blink setting. */
+/**
+ * vte_terminal_set_cursor_blinks:
+ * @terminal: a #VteTerminal
+ * @blink: TRUE if the cursor should blink
+ *
+ * Sets whether or not the cursor will blink.  The length of the blinking cycle
+ * is controlled by the "gtk-cursor-blink-time" GTK+ setting.
+ *
+ */
 void
 vte_terminal_set_cursor_blinks(VteTerminal *terminal, gboolean blink)
 {
@@ -13082,9 +13509,21 @@ vte_terminal_set_cursor_blinks(VteTerminal *terminal, gboolean blink)
 	terminal->pvt->cursor_blinks = blink;
 }
 
-/* Set the length of the scrollback buffers. */
+/**
+ * vte_terminal_set_scrollback_lines:
+ * @terminal: a #VteTerminal
+ * @lines: the length of the history buffer
+ *
+ * Sets the length of the scrollback buffer used by the terminal.  The size of
+ * the scrollback buffer will be set to the larger of this value and the number
+ * of visible rows the widget can display, so 0 can safely be used to disable
+ * scrollback.  Note that this setting only affects the normal screen buffer.
+ * For terminal types which have an alternate screen buffer, no scrollback is
+ * allowed.
+ *
+ */
 void
-vte_terminal_set_scrollback_lines(VteTerminal *terminal, long lines)
+vte_terminal_set_scrollback_lines(VteTerminal *terminal, glong lines)
 {
 	long highd, high, low, delta, max, next;
 	VteScreen *screens[2];
@@ -13134,9 +13573,17 @@ vte_terminal_set_scrollback_lines(VteTerminal *terminal, long lines)
 	vte_invalidate_all(terminal);
 }
 
-/* Set the list of characters we consider to be parts of words.  Everything
- * else will be a non-word character, and we'll use transitions between the
- * two sets when doing selection-by-words. */
+/**
+ * vte_terminal_set_word_chars:
+ * @terminal: a #VteTerminal
+ * @spec: a specification
+ *
+ * When the user double-clicks to start selection, the terminal will extend
+ * the selection on word boundaries.  It will treat characters included in @spec
+ * as parts of words, and all other characters as word separators.  Ranges of
+ * characters can be specified by separating them with a hyphen.
+ *
+ */
 void
 vte_terminal_set_word_chars(VteTerminal *terminal, const char *spec)
 {
@@ -13218,6 +13665,16 @@ vte_terminal_set_word_chars(VteTerminal *terminal, const char *spec)
 	g_free(obufptr);
 }
 
+/**
+ * vte_terminal_set_backspace_binding:
+ * @terminal: a #VteTerminal
+ * @binding: a #VteTerminalEraseBinding for the backspace key
+ *
+ * Modifies the terminal's backspace key binding, which controls what
+ * string or control sequence the terminal sends to its child when the user
+ * presses the backspace key.
+ *
+ */
 void
 vte_terminal_set_backspace_binding(VteTerminal *terminal,
 				   VteTerminalEraseBinding binding)
@@ -13227,6 +13684,16 @@ vte_terminal_set_backspace_binding(VteTerminal *terminal,
 	terminal->pvt->backspace_binding = binding;
 }
 
+/**
+ * vte_terminal_set_delete_binding:
+ * @terminal: a #VteTerminal
+ * @binding: a #VteTerminalEraseBinding for the delete key
+ *
+ * Modifies the terminal's delete key binding, which controls what
+ * string or control sequence the terminal sends to its child when the user
+ * presses the delete key.
+ *
+ */
 void
 vte_terminal_set_delete_binding(VteTerminal *terminal,
 				VteTerminalEraseBinding binding)
@@ -13235,6 +13702,17 @@ vte_terminal_set_delete_binding(VteTerminal *terminal,
 	terminal->pvt->delete_binding = binding;
 }
 
+/**
+ * vte_terminal_set_mouse_autohide:
+ * @terminal: a #VteTerminal
+ * @setting: TRUE if the autohide should be enabled
+ *
+ * Changes the value of the terminal's mouse autohide setting.  When autohiding
+ * is enabled, the mouse cursor will be hidden when the user presses a key and
+ * shown when the user moves the mouse.  This setting can be read using
+ * vte_terminal_get_mouse_autohide().
+ *
+ */
 void
 vte_terminal_set_mouse_autohide(VteTerminal *terminal, gboolean setting)
 {
@@ -13242,6 +13720,17 @@ vte_terminal_set_mouse_autohide(VteTerminal *terminal, gboolean setting)
 	terminal->pvt->mouse_autohide = setting;
 }
 
+/**
+ * vte_terminal_get_mouse_autohide:
+ * @terminal: a #VteTerminal
+ *
+ * Determines the value of the terminal's mouse autohide setting.  When
+ * autohiding is enabled, the mouse cursor will be hidden when the user presses
+ * a key and shown when the user moves the mouse.  This setting can be changed
+ * using vte_terminal_set_mouse_autohide().
+ *
+ * Returns: TRUE if autohiding is enabled, FALSE if not.
+ */
 gboolean
 vte_terminal_get_mouse_autohide(VteTerminal *terminal)
 {
@@ -13249,6 +13738,18 @@ vte_terminal_get_mouse_autohide(VteTerminal *terminal)
 	return terminal->pvt->mouse_autohide;
 }
 
+/**
+ * vte_terminal_reset:
+ * @terminal: a #VteTerminal
+ * @full: TRUE to reset tabstops
+ * @clear_history: TRUE to empty the terminal's scrollback buffer
+ *
+ * Resets as much of the terminal's internal state as possible, discarding any
+ * unprocessed input data, resetting character attributes, cursor state, 
+ * national character set state, status line, terminal modes (insert/delete),
+ * selection state, and encoding.
+ * 
+ */
 void
 vte_terminal_reset(VteTerminal *terminal, gboolean full, gboolean clear_history)
 {
@@ -13369,6 +13870,18 @@ vte_terminal_reset(VteTerminal *terminal, gboolean full, gboolean clear_history)
 	vte_invalidate_all(terminal);
 }
 
+/**
+ * vte_terminal_get_status_line:
+ * @terminal: a #VteTerminal
+ *
+ * Some terminal emulations specify a status line which is separate from the
+ * main display area, and define a means for applications to move the cursor
+ * to the status line and back.
+ *
+ * Returns: the current contents of the terminal's status line.  For terminals
+ * like "xterm", this will usually be the empty string.  The string must not
+ * be modified or freed by the caller.
+ */
 const char *
 vte_terminal_get_status_line(VteTerminal *terminal)
 {
@@ -13376,6 +13889,23 @@ vte_terminal_get_status_line(VteTerminal *terminal)
 	return terminal->pvt->screen->status_line_contents->str;
 }
 
+/**
+ * vte_terminal_get_padding:
+ * @terminal: a #VteTerminal
+ * @xpad: address in which to store left/right-edge padding
+ * @ypad: address in which to store top/bottom-edge ypadding
+ *
+ * Determines the amount of additional space the widget is using to pad the
+ * edges of its visible area.  This is necessary for cases where characters
+ * in the selected font don't themselves include a padding area and the
+ * text itself would be contiguous with the window border.  Applications
+ * which use the widget's #row_count, #column_count, #char_height, and
+ * #char_width fields to set geometry hints using
+ * gtk_window_set_geometry_hints() will need to add this value to the base
+ * size.  The values returned in @xpad and @ypad are the total padding used
+ * in each direction, and do not need to be doubled.
+ *
+ */
 void
 vte_terminal_get_padding(VteTerminal *terminal, int *xpad, int *ypad)
 {
diff --git a/src/vte.h b/src/vte.h
index 2664915..25613d7 100644
--- a/src/vte.h
+++ b/src/vte.h
@@ -44,12 +44,13 @@ struct _VteTerminal {
 	GtkAdjustment *adjustment;	/* Scrolling adjustment. */
 
 	/* Metric and sizing data. */
-	long char_width, char_height;	/* dimensions of character cells */
-	long char_ascent, char_descent; /* important font metrics */
-	long row_count, column_count;	/* dimensions of the window */
+	glong char_width, char_height;	/* dimensions of character cells */
+	glong char_ascent, char_descent; /* important font metrics */
+	glong row_count, column_count;	/* dimensions of the window */
 
 	/* Titles. */
-	char *window_title, *icon_title;
+	char *window_title;
+	char *icon_title;
 
 	/*< private >*/
 	VteTerminalPrivate *pvt;
@@ -98,7 +99,7 @@ typedef enum {
 	VTE_ERASE_AUTO,
 	VTE_ERASE_ASCII_BACKSPACE,
 	VTE_ERASE_ASCII_DELETE,
-	VTE_ERASE_DELETE_SEQUENCE,
+	VTE_ERASE_DELETE_SEQUENCE
 } VteTerminalEraseBinding;
 
 /* The structure we return as the supplemental attributes for strings. */
@@ -148,7 +149,8 @@ void vte_terminal_copy_primary(VteTerminal *terminal);
 void vte_terminal_paste_primary(VteTerminal *terminal);
 
 /* Set the terminal's size. */
-void vte_terminal_set_size(VteTerminal *terminal, long columns, long rows);
+void vte_terminal_set_size(VteTerminal *terminal,
+			   glong columns, glong rows);
 
 /* Set various one-off settings. */
 void vte_terminal_set_audible_bell(VteTerminal *terminal, gboolean is_audible);
@@ -186,7 +188,7 @@ void vte_terminal_set_background_transparent(VteTerminal *terminal,
 void vte_terminal_set_cursor_blinks(VteTerminal *terminal, gboolean blink);
 
 /* Set the number of scrollback lines, above or at an internal minimum. */
-void vte_terminal_set_scrollback_lines(VteTerminal *terminal, long lines);
+void vte_terminal_set_scrollback_lines(VteTerminal *terminal, glong lines);
 
 /* Append the input method menu items to a given shell. */
 void vte_terminal_im_append_menuitems(VteTerminal *terminal,
@@ -229,18 +231,19 @@ void vte_terminal_reset(VteTerminal *terminal, gboolean full,
  * Note that it will have one entry per byte, not per character, so indexes
  * should match up exactly. */
 char *vte_terminal_get_text(VteTerminal *terminal,
-			    gboolean(*is_selected)(VteTerminal * terminal,
-						   long column, long row),
+			    gboolean(*is_selected)(VteTerminal *terminal,
+						   glong column,
+						   glong row),
 			    GArray *attributes);
 char *vte_terminal_get_text_range(VteTerminal *terminal,
 				  glong start_row, glong start_col,
 				  glong end_row, glong end_col,
-				  gboolean(*is_selected)(VteTerminal * terminal,
-							 long column,
-							 long row),
+				  gboolean(*is_selected)(VteTerminal *terminal,
+							 glong column,
+							 glong row),
 				  GArray *attributes);
 void vte_terminal_get_cursor_position(VteTerminal *terminal,
-				      long *column, long *row);
+				      glong *column, glong *row);
 
 /* Display string matching:  clear all matching expressions. */
 void vte_terminal_match_clear_all(VteTerminal *terminal);
@@ -252,7 +255,8 @@ int vte_terminal_match_add(VteTerminal *terminal, const char *match);
 /* Check if a given cell on the screen contains part of a matched string.  If
  * it does, return the string, and store the match tag in the optional tag
  * argument. */
-char *vte_terminal_match_check(VteTerminal *terminal, long column, long row,
+char *vte_terminal_match_check(VteTerminal *terminal,
+			       glong column, glong row,
 			       int *tag);
 
 /* Set the emulation type.  Most of the time you won't need this. */
@@ -260,7 +264,7 @@ void vte_terminal_set_emulation(VteTerminal *terminal, const char *emulation);
 const char *vte_terminal_get_emulation(VteTerminal *terminal);
 
 /* Set the character encoding.  Most of the time you won't need this. */
-void vte_terminal_set_encoding(VteTerminal *terminal, const char *encoding);
+void vte_terminal_set_encoding(VteTerminal *terminal, const char *codeset);
 const char *vte_terminal_get_encoding(VteTerminal *terminal);
 
 /* Get the contents of the status line. */
diff --git a/src/vteaccess.c b/src/vteaccess.c
index 869b626..0679ba0 100644
--- a/src/vteaccess.c
+++ b/src/vteaccess.c
@@ -52,7 +52,7 @@ typedef struct _VteTerminalAccessiblePrivate {
 enum direction {
 	direction_previous = -1,
 	direction_current = 0,
-	direction_next = 1,
+	direction_next = 1
 };
 
 static gunichar vte_terminal_accessible_get_character_at_offset(AtkText *text,
@@ -75,7 +75,7 @@ vte_terminal_accessible_new_private_data(void)
 
 /* "Oh yeah, that's selected.  Sure."  */
 static gboolean
-all_selected(VteTerminal *terminal, long column, long row)
+all_selected(VteTerminal *terminal, glong column, glong row)
 {
 	return TRUE;
 }
@@ -308,6 +308,14 @@ vte_terminal_accessible_title_changed(VteTerminal *terminal, gpointer data)
 	atk_object_set_description(ATK_OBJECT(data), terminal->window_title);
 }
 
+/**
+ * vte_terminal_accessible_new:
+ * @terminal: a #VteTerminal
+ *
+ * Creates a new accessibility peer for the terminal widget.
+ *
+ * Returns: the new #AtkObject
+ */
 AtkObject *
 vte_terminal_accessible_new(VteTerminal *terminal)
 {
diff --git a/src/vteaccess.h b/src/vteaccess.h
index a209ac0..cd21e09 100644
--- a/src/vteaccess.h
+++ b/src/vteaccess.h
@@ -28,16 +28,18 @@
 G_BEGIN_DECLS
 
 /* The terminal accessibility object itself. */
-typedef struct _VteTerminalAccessible {
+typedef struct _VteTerminalAccessible VteTerminalAccessible;
+struct _VteTerminalAccessible {
 	GtkAccessible parent;
-} VteTerminalAccessible;
+};
 
 /* The object's class structure. */
-typedef struct _VteTerminalAccessibleClass {
+typedef struct _VteTerminalAccessibleClass VteTerminalAccessibleClass;
+struct _VteTerminalAccessibleClass {
 	/*< public > */
 	/* Inherited parent class. */
 	GtkAccessibleClass parent_class;
-} VteTerminalAccessibleClass;
+};
 
 /* The object's type. */
 GtkType vte_terminal_accessible_get_type(void);