[vte] Modernise the API docs

From: Christian Persch <chpe src gnome org>
To: svn-commits-list gnome org
Cc:
Subject: [vte] Modernise the API docs
Date: Thu, 14 Jan 2010 18:52:57 +0000 (UTC)
commit d8e791be89f38e168faf078268be8bdee4a6715d
Author: Christian Persch <chpe gnome org>
Date:   Thu Jan 14 18:42:06 2010 +0100

    Modernise the API docs
    
    Update to gtk-doc 0.13. Drop tmpl use, use <xi:include>, add object
    hierarchy, index, deprecated symbols index, and indices for new symbols
    in 0.20 and 0.24.

 autogen.sh                         |    3 +-
 configure.in                       |    9 +-
 doc/reference/Makefile.am          |  163 ++++--
 doc/reference/tmpl/internals.sgml  |   20 -
 doc/reference/tmpl/pty.sgml        |   18 -
 doc/reference/tmpl/reaper.sgml     |   25 -
 doc/reference/tmpl/vte-unused.sgml |  516 ---------------
 doc/reference/tmpl/vte.sgml        | 1287 ------------------------------------
 doc/reference/tmpl/vteaccess.sgml  |   37 -
 doc/reference/tmpl/vteversion.sgml |   59 --
 doc/reference/version.xml.in       |    1 +
 doc/reference/vte-docs.sgml        |   25 -
 doc/reference/vte-docs.xml         |  127 ++++
 doc/reference/vte-sections.txt     |   70 +-
 doc/reference/vte.types            |   12 +-
 src/reaper.c                       |   26 +
 src/reaper.h                       |    8 +
 src/vte.c                          |   32 +-
 src/vte.h                          |   98 +++-
 src/vteaccess.c                    |   10 +-
 src/vteaccess.h                    |   52 +-
 src/vteversion.h.in                |   47 ++
 22 files changed, 524 insertions(+), 2121 deletions(-)
---
diff --git a/autogen.sh b/autogen.sh
index a5e6990..f129ec6 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -27,7 +27,8 @@ which gnome-autogen.sh || {
 }
 
 USE_COMMON_DOC_BUILD=yes
-REQUIRED_AUTOMAKE_VERSION=1.9
+REQUIRED_AUTOMAKE_VERSION=1.10
 REQUIRED_INTLTOOL_VERSION=0.40.0
+REQUIRED_GTK_DOC_VERSION=0.13
 
 . gnome-autogen.sh
diff --git a/configure.in b/configure.in
index 482f949..961f4d1 100644
--- a/configure.in
+++ b/configure.in
@@ -3,6 +3,8 @@ m4_define([vte_version_minor],[23])
 m4_define([vte_version_micro],[5])
 m4_define([vte_version],[vte_version_major.vte_version_minor.vte_version_micro])
 
+m4_define([vte_api_version],[0])
+
 AC_PREREQ([2.59])
 AC_INIT(vte, [vte_version],
         [http://bugzilla.gnome.org/enter_bug.cgi?product=vte])
@@ -466,13 +468,17 @@ AM_CONDITIONAL([ENABLE_GLADE_CATALOGUE],[test "$enable_glade_catalogue" = "yes"]
 
 ################################################################################
 
-GTK_DOC_CHECK([1.0])
+GTK_DOC_CHECK([1.13],[--flavour no-tmpl])
+
+AC_SUBST([GLIB_PREFIX],[$($PKG_CONFIG --variable=prefix glib-2.0)])
+AC_SUBST([GTK_PREFIX],[$($PKG_CONFIG --variable=prefix gtk+-2.0)])
 
 ################################################################################
 
 AC_SUBST([VTE_MAJOR_VERSION],[vte_version_major])
 AC_SUBST([VTE_MINOR_VERSION],[vte_version_minor])
 AC_SUBST([VTE_MICRO_VERSION],[vte_version_micro])
+AC_SUBST([VTE_API_VERSION],[vte_api_version])
 
 ################################################################################
 
@@ -488,6 +494,7 @@ po/Makefile.in
 doc/Makefile
 doc/openi18n/Makefile
 doc/reference/Makefile
+doc/reference/version.xml
 glade/Makefile
 vte.pc
 vte-uninstalled.pc
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index b785920..7ce3f8e 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -1,22 +1,73 @@
-## Process this file with automake to create Makefile.in.
-
-# The name of the module.
-DOC_MODULE=vte
-
-# The top-level SGML file.
-DOC_MAIN_SGML_FILE=vte-docs.sgml
-
-# Extra options to supply to gtkdoc-scan
-SCAN_OPTIONS=--deprecated-guards="VTE_DISABLE_DEPRECATED"
-
-# The directory containing the source code. Relative to $(srcdir)
-DOC_SOURCE_DIR=../../src
-
-# Used for dependencies
-HFILE_GLOB= $(top_srcdir)/src/*.h
-CFILE_GLOB=$(top_srcdir)/src/*.c
-
-IGNORE_HFILES= \
+# We require automake 1.10 for $(abs_builddir)
+AUTOMAKE_OPTIONS = 1.10
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE = vte
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+# DOC_MODULE_VERSION = $(VTE_API_VERSION)
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR = ../../src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS =
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS = --deprecated-guards="VTE_DISABLE_DEPRECATED"
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS = --sgml-mode --output-format=xml --name-space=vte
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS =
+
+# Extra options to supply to gtkdoc-mkhtml
+# Add the builddir to the HTML path so that version.xml is found
+MKHTML_OPTIONS = --path="$(abs_builddir)"
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS = \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gio \
+	--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gdk \
+	--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gdk-pixbuf \
+	--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gtk
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB = \
+	$(top_srcdir)/src/*.h \
+	$(top_builddir)/src/*.h
+
+CFILE_GLOB = \
+	$(top_srcdir)/src/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+# EXTRA_HFILES = $(top_builddir)/vte/vteversion.h
+EXTRA_HFILES =
+
+# Header files to ignore when scanning. Use base file name, no paths
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES = \
+	config.h \
 	buffer.h \
 	caps.h \
 	debug.h \
@@ -44,34 +95,54 @@ IGNORE_HFILES= \
 	vteunistr.h \
 	vteunistr.h
 
-
-# CFLAGS and LDFLAGS for compiling scan program. Only needed
-# if $(DOC_MODULE).types is non-empty.
-GTKDOC_CFLAGS = $(VTE_CFLAGS) -I$(top_srcdir)/src -DVTE_COMPILATION
-GTKDOC_LIBS = $(top_builddir)/src/libvte.la
-
-# Extra options to supply to gtkdoc-mkdb
-MKDB_OPTIONS=--sgml-mode --output-format=xml
-
-# Extra options to supply to gtkdoc-fixref
-FIXXREF_OPTIONS=
-
-MAINTAINERCLEANFILES = vte-undocumented.txt
-
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES =
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files = \
+ 	version.xml
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files =
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS = \
+	-I$(top_srcdir) \
+	-I$(top_srcdir)/src \
+	-I$(top_builddir) \
+	-I$(top_builddir)/src \
+	-DVTE_COMPILATION \
+	$(VTE_CFLAGS)
+
+GTKDOC_LIBS = \
+	$(top_builddir)/src/libvte.la \
+	$(VTE_LIBS)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make
 
-# This line really belongs in gtk-doc.mk
-$(REPORT_FILES): sgml-build.stamp
-
-TESTS =
-
-if ENABLE_GTK_DOC
-TESTS += check-doc-coverage.sh
-endif
-
-TESTS += check-doc-syntax.sh
-EXTRA_DIST += check-doc-coverage.sh check-doc-syntax.sh
-
-TESTS_ENVIRONMENT = srcdir="$(srcdir)" top_srcdir="$(top_srcdir)" MAKE="$(MAKE) $(AM_MAKEFLAGS)" DOC_MODULE="$(DOC_MODULE)" REPORT_FILES="$(REPORT_FILES)"
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += \
+	version.xml.in
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+#DISTCLEANFILES +=
+
+# Comment this out if you want your docs-status tested during 'make check'
+#if ENABLE_GTK_DOC
+#TESTS_ENVIRONMENT = cd $(srcsrc) &&
+#TESTS = $(GTKDOC_CHECK)
+#endif
 
 -include $(top_srcdir)/git.mk
diff --git a/doc/reference/version.xml.in b/doc/reference/version.xml.in
new file mode 100644
index 0000000..d78bda9
--- /dev/null
+++ b/doc/reference/version.xml.in
@@ -0,0 +1 @@
+ VERSION@
diff --git a/doc/reference/vte-docs.xml b/doc/reference/vte-docs.xml
new file mode 100644
index 0000000..254ff14
--- /dev/null
+++ b/doc/reference/vte-docs.xml
@@ -0,0 +1,127 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
+  <!--
+    Copyright Â© 2009, 2010 Christian Persch
+
+    Permission is granted to copy, distribute and/or modify this document
+    under the terms of the GNU Free Documentation License, Version 1.2
+    or (at your option) any later version published by the Free Software Foundation;
+    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+
+    A copy of the license is included in the COPYING.DOC file.
+    -->
+
+  <bookinfo>
+    <title>VTE Reference Manual</title>
+    <releaseinfo>
+      Documentation for VTE version &version;.
+      The latest version of this documentation can be found on-line at the
+      <ulink role="online-location" url="http://library.gnome.org/devel/vte/";>GNOME Library</ulink>.
+    </releaseinfo>
+
+    <copyright>
+      <year>2009</year>
+      <year>2010</year>
+      <holder>Christian Persch</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this document
+        under the terms of the <citetitle>GNU Lesser General Public Licence</citetitle>, Version 2.1
+        or (at your option) any later version published by the Free Software Foundation.
+
+        You may obtain a copy of the <citetitle>GNU Lesser General Public Licence</citetitle>
+        from the Free Software Foundation at
+        <ulink type="http" url="http://www.gnu.org/licences/";>GNU Licences web site</ulink>
+        or by writing to:
+
+        <address>
+          The Free Software Foundation, Inc.,
+          <street>51 Franklin St</street> â?? Fifth Floor,
+          <city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode>,
+          <country>USA</country>
+        </address>
+      </para>
+    </legalnotice>
+  </bookinfo>
+
+  <part>
+    <title>API Reference</title>
+    <chapter>
+      <xi:include href="xml/vte-terminal.xml"/>
+    </chapter>
+    <chapter>
+      <xi:include href="xml/vte-version.xml"/>
+    </chapter>
+
+    <chapter id="internal-objects">
+      <title>Interna</title>
+      <xi:include href="xml/vte-access.xml"/>
+    </chapter>
+    <chapter id="deprecated-objects">
+      <title>Deprecated</title>
+      <xi:include href="xml/vte-reaper.xml"/>
+    </chapter>
+  </part>
+
+  <chapter id="object-hierarchy">
+  <title>Object Hierarchy</title>
+    <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+
+  <index id="api-index-full">
+    <title id="index-all">Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-deprecated" role="deprecated">
+    <title>Index of deprecated symbols</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-0-20" role="0.20">
+    <title>Index of new symbols in 0.20</title>
+    <xi:include href="xml/api-index-0.20.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="api-index-0-24" role="0.24">
+    <title>Index of new symbols in 0.24</title>
+    <xi:include href="xml/api-index-0.24.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <appendix id="licence">
+    <title>Licence</title>
+
+    <para>
+      This library is free software; you can redistribute it and/or
+      modify it under the terms of the <citetitle>GNU Lesser General Public
+      Licence</citetitle> as published by the Free Software Foundation; either
+      version 2.1 of the Licence, or (at your option) any later version.
+    </para>
+
+    <para>
+      This library is distributed in the hope that it will be useful,
+      but WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+      <citetitle>GNU Lesser General Public Licence</citetitle> for
+      more details.
+    </para>
+
+    <para>
+      You may obtain a copy of the <citetitle>GNU Lesser General Public Licence</citetitle>
+      from the Free Software Foundation at
+      <ulink type="http" url="http://www.gnu.org/licences/";>GNU Licences web site</ulink>
+      or by writing to:
+
+      <address>
+        The Free Software Foundation, Inc.,
+        <street>51 Franklin St</street> â?? Fifth Floor,
+        <city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode>,
+        <country>USA</country>
+      </address>
+    </para>
+  </appendix>
+
+</book>
diff --git a/doc/reference/vte-sections.txt b/doc/reference/vte-sections.txt
index 404e3ec..87d13ae 100644
--- a/doc/reference/vte-sections.txt
+++ b/doc/reference/vte-sections.txt
@@ -1,10 +1,11 @@
 <SECTION>
-<FILE>vte</FILE>
+<FILE>vte-terminal</FILE>
 <TITLE>VteTerminal</TITLE>
 VteTerminal
-VteTerminalEraseBinding
-VteTerminalCursorShape
+VteTerminalAntiAlias
 VteTerminalCursorBlinkMode
+VteTerminalCursorShape
+VteTerminalEraseBinding
 VteTerminalWriteFlags
 VteSelectionFunc
 vte_terminal_new
@@ -88,22 +89,24 @@ vte_terminal_get_status_line
 vte_terminal_get_padding
 vte_terminal_write_contents
 <SUBSECTION Standard>
-vte_terminal_cursor_blink_mode_get_type
-vte_terminal_cursor_shape_get_type
 VTE_TYPE_TERMINAL_CURSOR_BLINK_MODE
+vte_terminal_cursor_blink_mode_get_type
 VTE_TYPE_TERMINAL_CURSOR_SHAPE
-vte_terminal_erase_binding_get_type
+vte_terminal_cursor_shape_get_type
 VTE_TYPE_TERMINAL_ERASE_BINDING
-VTE_IS_TERMINAL_ERASE_BINDING
+vte_terminal_erase_binding_get_type
+VTE_TYPE_TERMINAL_WRITE_FLAGS
+vte_terminal_write_flags_get_type
+VTE_TYPE_TERMINAL_ANTI_ALIAS
+vte_terminal_anti_alias_get_type
 VTE_TYPE_TERMINAL
+vte_terminal_get_type
 VTE_IS_TERMINAL
 VTE_TERMINAL
-vte_terminal_get_type
 VTE_TERMINAL_GET_CLASS
 VTE_IS_TERMINAL_CLASS
 VTE_TERMINAL_CLASS
-VTE_TYPE_TERMINAL_WRITE_FLAGS
-vte_terminal_write_flags_get_type
+
 <SUBSECTION Binding Accessors>
 vte_terminal_get_adjustment
 vte_terminal_get_char_ascent
@@ -114,20 +117,29 @@ vte_terminal_get_column_count
 vte_terminal_get_icon_title
 vte_terminal_get_row_count
 vte_terminal_get_window_title
+
+<SUBSECTION Private>
+VTE_IS_TERMINAL_ANTI_ALIAS
+VTE_IS_TERMINAL_ERASE_BINDING
+VteCharAttributes
+VteTerminalPrivate
 </SECTION>
 
 <SECTION>
-<FILE>vteversion</FILE>
+<FILE>vte-version</FILE>
 <TITLE>Version Information</TITLE>
-<SUBSECTION>
+
 VTE_MAJOR_VERSION
 VTE_MINOR_VERSION
 VTE_MICRO_VERSION
+
+<SUBSECTION>
 VTE_CHECK_VERSION
+
 </SECTION>
 
 <SECTION>
-<FILE>vteaccess</FILE>
+<FILE>vte-access</FILE>
 <TITLE>VteTerminalAccessible</TITLE>
 VteTerminalAccessible
 vte_terminal_accessible_new
@@ -137,45 +149,33 @@ VTE_IS_TERMINAL_ACCESSIBLE_CLASS
 VTE_IS_TERMINAL_ACCESSIBLE_FACTORY
 VTE_IS_TERMINAL_ACCESSIBLE_FACTORY_CLASS
 VTE_TERMINAL_ACCESSIBLE
-VteTerminalAccessibleClass
 VTE_TERMINAL_ACCESSIBLE_CLASS
-VteTerminalAccessibleFactory
 VTE_TERMINAL_ACCESSIBLE_FACTORY
-VteTerminalAccessibleFactoryClass
 VTE_TERMINAL_ACCESSIBLE_FACTORY_CLASS
 VTE_TERMINAL_ACCESSIBLE_FACTORY_GET_CLASS
-vte_terminal_accessible_factory_get_type
-vte_terminal_accessible_factory_new
 VTE_TERMINAL_ACCESSIBLE_GET_CLASS
 vte_terminal_accessible_get_type
 VTE_TYPE_TERMINAL_ACCESSIBLE
+vte_terminal_accessible_factory_get_type
 VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY
+VteTerminalAccessibleFactory
+VteTerminalAccessibleFactoryClass
+vte_terminal_accessible_factory_new
 </SECTION>
 
 <SECTION>
-<FILE>internals</FILE>
-<TITLE>Internals</TITLE>
-<SUBSECTION Private>
-
-VTE_IS_TERMINAL_ANTI_ALIAS
-VTE_TYPE_TERMINAL_ANTI_ALIAS
-VteCharAttributes
-VteTerminalAntiAlias
-VteTerminalPrivate
-vte_terminal_anti_alias_get_type
-
-VteReaperClass
-VteTerminalClass
+<FILE>vte-reaper</FILE>
+<TITLE>VteReaper</TITLE>
+VteReaper
+vte_reaper_add_child
+vte_reaper_get
 
+<SUBSECTION Standard>
 VTE_IS_REAPER
 VTE_IS_REAPER_CLASS
 VTE_REAPER
 VTE_REAPER_CLASS
 VTE_REAPER_GET_CLASS
 VTE_TYPE_REAPER
-VteReaper
-vte_reaper_add_child
-vte_reaper_get
 vte_reaper_get_type
-
 </SECTION>
diff --git a/doc/reference/vte.types b/doc/reference/vte.types
index e50bc5b..94d16d9 100644
--- a/doc/reference/vte.types
+++ b/doc/reference/vte.types
@@ -1,11 +1,21 @@
 #include <glib.h>
 #include <glib-object.h>
+#include <gio/gio.h>
 #include <gtk/gtk.h>
 #include "vte.h"
 #include "vteversion.h"
 #include "vteaccess.h"
+#include "vtetypebuiltins.h"
 #include "reaper.h"
 
+vte_reaper_get_type
+
 vte_terminal_get_type
 vte_terminal_accessible_get_type
-vte_reaper_get_type
+vte_terminal_accessible_factory_get_type
+
+vte_terminal_anti_alias_get_type
+vte_terminal_cursor_blink_mode_get_type
+vte_terminal_cursor_shape_get_type
+vte_terminal_erase_binding_get_type
+vte_terminal_write_flags_get_type
diff --git a/src/reaper.c b/src/reaper.c
index 309db12..35ae488 100644
--- a/src/reaper.c
+++ b/src/reaper.c
@@ -16,6 +16,21 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
+/**
+ * SECTION: vte-reaper
+ * @short_description: A singleton object which catches %SIGCHLD signals and
+ * converts them into GObject-style &quot;child-exited&quot; signals
+ *
+ * Because an application may need to be notified when child processes
+ * exit, and because there is only one %SIGCHLD handler, the #VteTerminal
+ * widget relies on a #VteReaper to watch for %SIGCHLD notifications and
+ * retrieve the exit status of child processes which have exited.  When
+ * glib provides child_watch functionality, the #VteReaper merely acts as
+ * a proxy for glib's own functionality.
+ *
+ * Since 0.11.11
+ */
+
 #include <config.h>
 
 #include "debug.h"
@@ -89,6 +104,17 @@ vte_reaper_class_init(VteReaperClass *klass)
 {
 	GObjectClass *gobject_class;
 
+        /**
+         * VteReaper::child-exited:
+         * @vtereaper: the object which received the signal
+         * @arg1: the process ID of the exited child
+         * @arg2: the status of the exited child, as returned by waitpid()
+         * 
+         * Emitted when the #VteReaper object detects that a child of the
+         * current process has exited.
+         *
+         * Since: 0.11.11
+         */
 	klass->child_exited_signal = g_signal_new(g_intern_static_string("child-exited"),
 						  G_OBJECT_CLASS_TYPE(klass),
 						  G_SIGNAL_RUN_LAST,
diff --git a/src/reaper.h b/src/reaper.h
index 791cb17..d67498e 100644
--- a/src/reaper.h
+++ b/src/reaper.h
@@ -28,8 +28,15 @@
 
 G_BEGIN_DECLS
 
+/**
+ * VteReaper:
+ *
+ * The reaper object.
+ */
 struct _VteReaper {
 	GObject object;
+
+        /*< private >*/
 	GIOChannel *_channel; /* unused */
 	int _iopipe[2]; /* unused */
 };
@@ -37,6 +44,7 @@ typedef struct _VteReaper VteReaper;
 
 struct _VteReaperClass {
 	GObjectClass parent_class;
+        /*< private >*/
 	guint child_exited_signal;
 };
 typedef struct _VteReaperClass VteReaperClass;
diff --git a/src/vte.c b/src/vte.c
index e47bef1..0175972 100644
--- a/src/vte.c
+++ b/src/vte.c
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2001-2004,2009,2010 Red Hat, Inc.
+ * Copyright Â© 2009, 2010 Christian Persch
  *
  * This is free software; you can redistribute it and/or modify it under
  * the terms of the GNU Library General Public License as published by
@@ -16,6 +17,13 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
+/**
+ * SECTION: vte-terminal
+ * @short_description: A terminal widget implementation
+ *
+ * A VteTerminal is a terminal emulator implemented as a GTK2 widget.
+ */
+
 #include <config.h>
 
 #include <math.h>
@@ -7378,7 +7386,7 @@ vte_terminal_ensure_font (VteTerminal *terminal)
  *
  * Since: 0.11.11
  * 
- * Deprecated: 0.19.1
+ * Deprecated: 0.20
  */
 void
 vte_terminal_set_font_full(VteTerminal *terminal,
@@ -7498,7 +7506,7 @@ vte_terminal_set_font_from_string_full_internal(VteTerminal *terminal,
  *
  * Since: 0.11.11
  *
- * Deprecated: 0.19.1
+ * Deprecated: 0.20
  */
 void
 vte_terminal_set_font_from_string_full(VteTerminal *terminal, const char *name,
@@ -12810,7 +12818,7 @@ vte_terminal_get_has_selection(VteTerminal *terminal)
  *
  * Returns: %TRUE
  *
- * Deprecated: 0.19.1
+ * Deprecated: 0.20
  */
 gboolean
 vte_terminal_get_using_xft(VteTerminal *terminal)
@@ -13502,7 +13510,7 @@ vte_terminal_get_char_height(VteTerminal *terminal)
  *
  * Returns: the contents of @terminal's char_descent field
  *
- * Deprecated: 0.19.1
+ * Deprecated: 0.20
  */
 glong
 vte_terminal_get_char_descent(VteTerminal *terminal)
@@ -13520,7 +13528,7 @@ vte_terminal_get_char_descent(VteTerminal *terminal)
  *
  * Returns: the contents of @terminal's char_ascent field
  *
- * Deprecated: 0.19.1
+ * Deprecated: 0.20
  */
 glong
 vte_terminal_get_char_ascent(VteTerminal *terminal)
@@ -14271,8 +14279,6 @@ update_timeout (gpointer data)
 	return FALSE;
 }
 
-
-
 /**
  * vte_terminal_write_contents:
  * @terminal: a #VteTerminal
@@ -14296,12 +14302,14 @@ update_timeout (gpointer data)
  *
  * Since: 0.24
  */
-gboolean vte_terminal_write_contents (VteTerminal *terminal,
-				      GOutputStream *stream,
-				      VteTerminalWriteFlags flags,
-				      GCancellable *cancellable,
-				      GError **error)
+gboolean
+vte_terminal_write_contents (VteTerminal *terminal,
+                             GOutputStream *stream,
+                             VteTerminalWriteFlags flags,
+                             GCancellable *cancellable,
+                             GError **error)
 {
+        g_return_val_if_fail(VTE_IS_TERMINAL(terminal), FALSE);
 	return _vte_ring_write_contents (terminal->pvt->screen->row_data,
 					 stream, flags,
 					 cancellable, error);
diff --git a/src/vte.h b/src/vte.h
index 3b64239..8cd4372 100644
--- a/src/vte.h
+++ b/src/vte.h
@@ -40,6 +40,22 @@ typedef struct _VteTerminalPrivate VteTerminalPrivate;
 
 /* The terminal widget itself. */
 typedef struct _VteTerminal VteTerminal;
+
+/**
+ * VteTerminal:
+ * @widget: Base #GtkWidget of the terminal widget.
+ * @adjustment: Scroll bar adjustments.
+ * @char_width: Width of a narrow character cell.
+ * @char_height: Height of a character cell.
+ * @char_ascent: The distance (in pixels) from the baseline of drawn text to the top of the character cell.
+ * @char_descent: The distance (in pixels) from the baseline of drawn text to the bottom of the character cell.
+ * @row_count: Number of visible rows.
+ * @column_count: Number of visible columns.
+ * @window_title: The terminal's idea of what the window's title should be.
+ * @icon_title: The terminal's idea of what the window's title should be when iconified.
+ * 
+ * All of these fields should be considered read-only.
+ */
 struct _VteTerminal {
 	/*< public >*/
 
@@ -62,6 +78,12 @@ struct _VteTerminal {
 
 /* The widget's class structure. */
 typedef struct _VteTerminalClass VteTerminalClass;
+
+/**
+ * VteTerminalClass:
+ *
+ * All of these fields should be considered read-only, except for derived classes.
+ */
 struct _VteTerminalClass {
 	/*< public > */
 	/* Inherited parent class. */
@@ -153,8 +175,18 @@ struct _VteTerminalClass {
 	guint reserved6;
 };
 
-/* Values for "what should happen when the user hits backspace/delete".  Use
- * AUTO unless the user can cause them to be overridden. */
+/**
+ * VteTerminalEraseBinding:
+ * @VTE_ERASE_AUTO: For backspace, attempt to determine the right value from the terminal's IO settings.  For delete, use the control sequence.
+ * @VTE_ERASE_ASCII_BACKSPACE: Send an ASCII backspace character (0x08).
+ * @VTE_ERASE_ASCII_DELETE: Send an ASCII delete character (0x7F).
+ * @VTE_ERASE_DELETE_SEQUENCE: Send the "@@7" control sequence.
+ * @VTE_ERASE_TTY: Send terminal's "erase" setting.
+ *
+ * An enumerated type which can be used to indicate which string the terminal
+ * should send to an application when the user presses the Delete or Backspace
+ * keys.
+ */
 typedef enum {
 	VTE_ERASE_AUTO,
 	VTE_ERASE_ASCII_BACKSPACE,
@@ -163,14 +195,31 @@ typedef enum {
 	VTE_ERASE_TTY
 } VteTerminalEraseBinding;
 
-/* Values for the cursor blink setting */
+/**
+ * VteTerminalCursorBlinkMode:
+ * @VTE_CURSOR_BLINK_SYSTEM: Follow GTK+ settings for cursor blinking.
+ * @VTE_CURSOR_BLINK_ON: Cursor blinks.
+ * @VTE_CURSOR_BLINK_OFF: Cursor does not blink.
+ *
+ * An enumerated type which can be used to indicate the cursor blink mode
+ * for the terminal.
+ */
 typedef enum {
         VTE_CURSOR_BLINK_SYSTEM,
         VTE_CURSOR_BLINK_ON,
         VTE_CURSOR_BLINK_OFF
 } VteTerminalCursorBlinkMode;
 
-/* Values for the cursor shape setting */
+/**
+ * VteTerminalCursorShape:
+ * @VTE_CURSOR_SHAPE_BLOCK: Draw a block cursor.  This is the default.
+ * @VTE_CURSOR_SHAPE_IBEAM: Draw a vertical bar on the left side of character.
+ * This is similar to the default cursor for other GTK+ widgets.
+ * @VTE_CURSOR_SHAPE_UNDERLINE: Draw a horizontal bar below the character.
+ *
+ * An enumerated type which can be used to indicate what should the terminal
+ * draw at the cursor position.
+ */
 typedef enum {
         VTE_CURSOR_SHAPE_BLOCK,
         VTE_CURSOR_SHAPE_IBEAM,
@@ -179,6 +228,7 @@ typedef enum {
 
 /* The structure we return as the supplemental attributes for strings. */
 struct _VteCharAttributes {
+        /*< private >*/
 	long row, column;
 	GdkColor fore, back;
 	guint underline:1, strikethrough:1;
@@ -187,6 +237,7 @@ typedef struct _VteCharAttributes VteCharAttributes;
 
 /* The name of the same structure in the 0.10 series, for API compatibility. */
 struct vte_char_attributes {
+        /*< private >*/
 	long row, column;
 	GdkColor fore, back;
 	guint underline:1, strikethrough:1;
@@ -399,7 +450,7 @@ const char *vte_terminal_get_status_line(VteTerminal *terminal);
 
 #ifndef VTE_DISABLE_DEPRECATED
 /* Get the padding the widget is using. */
-void vte_terminal_get_padding(VteTerminal *terminal, int *xpad, int *ypad);
+void vte_terminal_get_padding(VteTerminal *terminal, int *xpad, int *ypad) G_GNUC_DEPRECATED;
 #endif
 
 /* Attach an existing PTY master side to the terminal widget.  Use
@@ -421,6 +472,13 @@ int vte_terminal_get_child_exit_status(VteTerminal *terminal);
 
 /* Writing contents out */
 
+/**
+ * VteTerminalWriteFlags:
+ * @VTE_TERMINAL_WRITE_DEFAULT: Write contents as UTF-8 text.  This is the default.
+ *
+ * A flag type to determine how terminal contents should be written
+ * to an output stream.
+ */
 typedef enum {
   VTE_TERMINAL_WRITE_DEFAULT = 0
 } VteTerminalWriteFlags;
@@ -434,10 +492,38 @@ gboolean vte_terminal_write_contents (VteTerminal *terminal,
 
 #ifndef VTE_DISABLE_DEPRECATED
 
+/**
+ * VTE_IS_TERMINAL_ERASE_BINDING:
+ *
+ * Does nothing.
+ *
+ * Returns: %FALSE
+ *
+ * @Deprecated: 0.20
+ */
 #define VTE_IS_TERMINAL_ERASE_BINDING(obj)  (FALSE)
+
+/**
+ * VTE_IS_TERMINAL_ANTI_ALIAS:
+ *
+ * Does nothing.
+ *
+ * Returns: %FALSE
+ *
+ * @Deprecated: 0.20
+ */
 #define VTE_IS_TERMINAL_ANTI_ALIAS(obj)     (FALSE)
 
-/* Values for the anti alias setting */
+/**
+ * VteTerminalAntiAlias:
+ * @VTE_ANTI_ALIAS_USE_DEFAULT: Use the system default anti-alias setting
+ * @VTE_ANTI_ALIAS_FORCE_ENABLE: Force enable anti-aliasing
+ * @VTE_ANTI_ALIAS_FORCE_DISABLE: Force disable anti-aliasing
+ *
+ * An enumeration describing which anti-alias setting to use.
+ *
+ * @Deprecated: 0.20
+ */
 typedef enum {
 	VTE_ANTI_ALIAS_USE_DEFAULT,
 	VTE_ANTI_ALIAS_FORCE_ENABLE,
diff --git a/src/vteaccess.c b/src/vteaccess.c
index 3c87553..15730cb 100644
--- a/src/vteaccess.c
+++ b/src/vteaccess.c
@@ -16,9 +16,13 @@
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-/* VTE accessibility object.  Based heavily on inspection of libzvt's
- * accessibility code. */
-
+/**
+ * SECTION: vte-access
+ * @short_description: Accessibility peer of #VteTerminal
+ *
+ * The accessibility peer of a #VteTerminal, implementing GNOME's accessibility
+ * framework.
+ */
 
 #include <config.h>
 
diff --git a/src/vteaccess.h b/src/vteaccess.h
index d974f51..7204d37 100644
--- a/src/vteaccess.h
+++ b/src/vteaccess.h
@@ -26,65 +26,59 @@
 
 G_BEGIN_DECLS
 
-/* The terminal accessibility object itself. */
+#define VTE_TYPE_TERMINAL_ACCESSIBLE            (vte_terminal_accessible_get_type ())
+#define VTE_TERMINAL_ACCESSIBLE(object)         (G_TYPE_CHECK_INSTANCE_CAST ((object), VTE_TYPE_TERMINAL_ACCESSIBLE, VteTerminalAccessible))
+#define VTE_TERMINAL_ACCESSIBLE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE, VteTerminalAccessibleClass))
+#define VTE_IS_TERMINAL_ACCESSIBLE(object)      (G_TYPE_CHECK_INSTANCE_TYPE ((object), VTE_TYPE_TERMINAL_ACCESSIBLE))
+#define VTE_IS_TERMINAL_ACCESSIBLE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE))
+#define VTE_TERMINAL_ACCESSIBLE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), VTE_TYPE_TERMINAL_ACCESSIBLE, VteTerminalAccessibleClass))
+
 typedef struct _VteTerminalAccessible VteTerminalAccessible;
+typedef struct _VteTerminalAccessibleClass VteTerminalAccessibleClass;
+
+/**
+ * VteTerminalAccessible:
+ *
+ * The accessible peer for #VteTerminal.
+ */
 struct _VteTerminalAccessible {
-	/*< public > */
 	GtkAccessible parent;
 	/*< private > */
 	/* Unknown GailWidget implementation stuffs, exact size of which is
 	 * worked out at run-time. */
 };
 
-/* The object's class structure. */
-typedef struct _VteTerminalAccessibleClass VteTerminalAccessibleClass;
 struct _VteTerminalAccessibleClass {
-	/*< public > */
-	/* Inherited parent class. */
 	GtkAccessibleClass parent_class;
 	/*< private > */
 	/* Unknown GailWidgetClass implementation stuffs, exact size of which
 	 * is worked out at run-time. */
 };
 
-/* The object's type. */
 GType vte_terminal_accessible_get_type(void);
 
-#define VTE_TYPE_TERMINAL_ACCESSIBLE              (vte_terminal_accessible_get_type ())
-#define VTE_TERMINAL_ACCESSIBLE(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), VTE_TYPE_TERMINAL_ACCESSIBLE, VteTerminalAccessible))
-#define VTE_TERMINAL_ACCESSIBLE_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE, VteTerminalAccessibleClass))
-#define VTE_IS_TERMINAL_ACCESSIBLE(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), VTE_TYPE_TERMINAL_ACCESSIBLE))
-#define VTE_IS_TERMINAL_ACCESSIBLE_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE))
-#define VTE_TERMINAL_ACCESSIBLE_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), VTE_TYPE_TERMINAL_ACCESSIBLE, VteTerminalAccessibleClass))
-
 AtkObject *vte_terminal_accessible_new(VteTerminal *terminal);
 
-/* The terminal accessibility object's factory. */
+#define VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY            (vte_terminal_accessible_factory_get_type ())
+#define VTE_TERMINAL_ACCESSIBLE_FACTORY(object)         (G_TYPE_CHECK_INSTANCE_CAST ((object), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY, VteTerminalAccessibleFactory))
+#define VTE_TERMINAL_ACCESSIBLE_FACTORY_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY, VteTerminalAccessibleFactoryClass))
+#define VTE_IS_TERMINAL_ACCESSIBLE_FACTORY(object)      (G_TYPE_CHECK_INSTANCE_TYPE ((object), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY))
+#define VTE_IS_TERMINAL_ACCESSIBLE_FACTORY_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY))
+#define VTE_TERMINAL_ACCESSIBLE_FACTORY_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY, VteTerminalAccessibleFactoryClass))
+
 typedef struct _VteTerminalAccessibleFactory VteTerminalAccessibleFactory;
+typedef struct _VteTerminalAccessibleFactoryClass VteTerminalAccessibleFactoryClass;
+
 struct _VteTerminalAccessibleFactory {
-	/*< public > */
 	AtkObjectFactory parent;
-	/*< private > */
 };
 
-/* The object's class structure. */
-typedef struct _VteTerminalAccessibleFactoryClass VteTerminalAccessibleFactoryClass;
 struct _VteTerminalAccessibleFactoryClass {
-	/*< public > */
 	AtkObjectFactoryClass parent;
-	/*< private > */
 };
 
-/* The object's factory's type. */
 GType vte_terminal_accessible_factory_get_type(void);
 
-#define VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY              (vte_terminal_accessible_factory_get_type ())
-#define VTE_TERMINAL_ACCESSIBLE_FACTORY(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY, VteTerminalAccessibleFactory))
-#define VTE_TERMINAL_ACCESSIBLE_FACTORY_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY, VteTerminalAccessibleFactoryClass))
-#define VTE_IS_TERMINAL_ACCESSIBLE_FACTORY(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY))
-#define VTE_IS_TERMINAL_ACCESSIBLE_FACTORY_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY))
-#define VTE_TERMINAL_ACCESSIBLE_FACTORY_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), VTE_TYPE_TERMINAL_ACCESSIBLE_FACTORY, VteTerminalAccessibleFactoryClass))
-
 AtkObjectFactory *vte_terminal_accessible_factory_new(void);
 
 G_END_DECLS
diff --git a/src/vteversion.h.in b/src/vteversion.h.in
index 23e82fe..0f801b7 100644
--- a/src/vteversion.h.in
+++ b/src/vteversion.h.in
@@ -23,10 +23,57 @@
 #ifndef vte_vteversion_h_included
 #define vte_vteversion_h_included
 
+/**
+ * SECTION:vte-version
+ * @short_description: Library version checks
+ *
+ * These macros enable compile time checks of the library version.
+ *
+ * Since: 0.16.15
+ */
+
+/**
+ * VTE_MAJOR_VERSION:
+ *
+ * The major version number of the VTE library
+ * (e.g. in version 3.1.4 this is 3).
+ *
+ * Since: 0.16.15
+ */
 #define VTE_MAJOR_VERSION (@VTE_MAJOR_VERSION@)
+
+/**
+ * VTE_MINOR_VERSION:
+ *
+ * The minor version number of the VTE library
+ * (e.g. in version 3.1.4 this is 1).
+ *
+ * Since: 0.16.15
+ */
 #define VTE_MINOR_VERSION (@VTE_MINOR_VERSION@)
+
+/**
+ * VTE_MICRO_VERSION:
+ *
+ * The micro version number of the VTE library
+ * (e.g. in version 3.1.4 this is 4).
+ *
+ * Since: 0.16.15
+ */
 #define VTE_MICRO_VERSION (@VTE_MICRO_VERSION@)
 
+/**
+ * VTE_CHECK_VERSION:
+ * @major: required major version
+ * @minor: required minor version
+ * @micro: required micro version
+ *
+ * Macro to check the library version at compile time.
+ * It returns %1 if the version of VTE is greater or
+ * equal to the required one, and %0 otherwise.
+ *
+ * Since: 0.16.15
+ */
 #define VTE_CHECK_VERSION(major,minor,micro) \
   (VTE_MAJOR_VERSION > (major) || \
    (VTE_MAJOR_VERSION == (major) && VTE_MINOR_VERSION > (minor)) || \
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]