Add some gtk-doc documentation.

ChangeLog

@@ -1,3 +1,24 @@
+Tue Jun 06 00:14:00 PDT 2006  Christian Hammond <chipx86@chipx86.com>
+
+	A docs/reference/libnotify-docs.sgml:
+	A docs/reference/libnotify-overrides.txt:
+	A docs/reference/libnotify-sections.txt:
+	A docs/reference/tmpl:
+	A docs/reference/tmpl/libnotify-docs.sgml:
+	A docs/reference/tmpl/libnotify-unused.sgml:
+	A docs/reference/tmpl/notification.sgml:
+	A docs/reference/tmpl/notify.sgml:
+	A docs/reference/Makefile.am:
+	A docs/Makefile.am:
+	* libnotify/notification.c:
+	* libnotify/notification.h:
+	* libnotify/notify.c:
+	D Doxyfile.in:
+	* Makefile.am:
+	* autogen.sh:
+	* configure.ac:
+	  - Add some gtk-doc documentation.
+
 Sun Jun 04 17:44:27 PDT 2006  Christian Hammond <chipx86@chipx86.com>
 
 	* libnotify/notification.c:

Makefile.am

@@ -1,4 +1,4 @@
-SUBDIRS = libnotify tools tests
+SUBDIRS = libnotify docs tools tests
 
 pcdata_DATA = libnotify.pc
 pcdatadir = $(libdir)/pkgconfig
@@ -22,3 +22,5 @@ libtool: $(LIBTOOL_DEPS)
 doxygen:
 	@echo "Running doxygen..."
 	@doxygen Doxyfile
+
+DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc

autogen.sh

@@ -31,12 +31,21 @@ echo "Generating configuration files for $PACKAGE, please wait..."
 	DIE=1
 }
 
+(gtkdocize --version) < /dev/null > /dev/null 2>&1 || {
+	echo
+	echo "You must have gtkdocize installed to compile $PACKAGE."
+	echo "Download the appropriate package for your distribution,"
+	echo "or get the source tarball at ftp://ftp.gnome.org/pub/gnome/sources/gtk-doc"
+}
+
 [ $DIE -eq 1 ] && exit 1;
 
 echo "  libtoolize --copy --force"
 libtoolize --copy --force
 echo "  aclocal $ACLOCAL_FLAGS"
 aclocal $ACLOCAL_FLAGS
+echo "  gtkdocize"
+gtkdocize
 echo "  autoheader"
 autoheader
 echo "  automake --add-missing"

configure.ac

@@ -20,12 +20,7 @@ LIBGALAGO_DEVEL_VERSION=90
 LIBGALAGO_VERSION=$LIBGALAGO_MAJOR_VERSION.$LIBGALAGO_MINOR_VERSION.$LIBGALAGO_MICRO_VERSION
 
 if test "x$LIBGALAGO_DEVEL_VERSION" != "x0"; then
-	if test "x$LIBGALAGO_MICRO_VERSION" = "x0"; then
+	LIBGALAGO_VERSION=$LIBGALAGO_VERSION.$LIBGALAGO_DEVEL_VERSION
-		LIBGALAGO_MICRO_VERSION=$LIBGALAGO_DEVEL_VERSION
-		LIBGALAGO_VERSION=$LIBGALAGO_MAJOR_VERSION.$LIBGALAGO_MINOR_VERSION.$LIBGALAGO_DEVEL_VERSION
-	else
-		LIBGALAGO_VERSION=$LIBGALAGO_VERSION.$LIBGALAGO_DEVEL_VERSION
-	fi
 fi
 
 AC_DEFINE_UNQUOTED(LIBGALAGO_MAJOR_VERSION, $LIBGALAGO_MAJOR_VERSION,
@@ -114,6 +109,13 @@ AC_DEFINE_UNQUOTED(DBUS_MICRO_VER, $DBUS_MICRO_VER, [D-BUS micro version.])
 
 AC_DEFINE_UNQUOTED(DBUS_API_SUBJECT_TO_CHANGE, ,DBUS API is subject to change)
 
+
+dnl ################################################################
+dnl # Set up gtk-doc
+dnl ################################################################
+GTK_DOC_CHECK([1.4])
+
+
 dnl # Use wall if we have GCC
 if test "x$GCC" = "xyes"; then
 	CFLAGS="$CFLAGS -Wall"
@@ -125,8 +127,9 @@ dnl ################################################################
 dnl # Output the Makefiles
 dnl ################################################################
 AC_CONFIG_FILES([
-Doxyfile
 Makefile
+docs/Makefile
+docs/reference/Makefile
 libnotify.pc
 libnotify/Makefile
 tests/Makefile
@@ -142,4 +145,3 @@ echo
 echo "Now type make to compile"
 echo "Then su to root and type: make install"
 echo
-

docs/Makefile.am

@@ -0,0 +1,5 @@
+SUBDIRS = reference
+
+EXTRA_DIST = \
+	ChangeLog \
+	notification-spec.xml

docs/reference/Makefile.am

@@ -0,0 +1,81 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# 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=libnotify
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# 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=../../libnotify
+
+# 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=
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# 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=
+
+# 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)/libnotify/*.h
+CFILE_GLOB=$(top_srcdir)/libnotify/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=			\
+	notify-enum-types.h	\
+	notify-marshal.h		\
+	internal.h
+
+# 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=
+
+# 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. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(PACKAGE_CFLAGS)
+GTKDOC_LIBS=$(PACKAGE_LIBS) $(top_builddir)/libnotify/libnotify.la
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += 

docs/reference/libnotify-docs.sgml

@@ -0,0 +1,14 @@
+<?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">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>[Insert name here] Reference Manual</title>
+  </bookinfo>
+
+  <chapter>
+    <title>[Insert title here]</title>
+    <xi:include href="xml/notification.xml"/>
+    <xi:include href="xml/notify.xml"/>
+  </chapter>
+</book>

docs/reference/libnotify-sections.txt

@@ -0,0 +1,50 @@
+<SECTION>
+<FILE>notification</FILE>
+NOTIFY_EXPIRES_DEFAULT
+NOTIFY_EXPIRES_NEVER
+NotifyNotificationPrivate
+<TITLE>NotifyNotification</TITLE>
+NotifyNotification
+NotifyUrgency
+NotifyActionCallback
+NOTIFY_ACTION_CALLBACK
+notify_notification_new
+notify_notification_new_with_status_icon
+notify_notification_update
+notify_notification_attach_to_widget
+notify_notification_attach_to_status_icon
+notify_notification_set_geometry_hints
+notify_notification_show
+notify_notification_set_timeout
+notify_notification_set_category
+notify_notification_set_urgency
+notify_notification_set_icon_from_pixbuf
+notify_notification_set_hint_int32
+notify_notification_set_hint_double
+notify_notification_set_hint_string
+notify_notification_set_hint_byte
+notify_notification_set_hint_byte_array
+notify_notification_clear_hints
+notify_notification_add_action
+notify_notification_clear_actions
+notify_notification_close
+<SUBSECTION Standard>
+NOTIFY_NOTIFICATION
+NOTIFY_IS_NOTIFICATION
+NOTIFY_TYPE_NOTIFICATION
+notify_notification_get_type
+NOTIFY_NOTIFICATION_CLASS
+NOTIFY_IS_NOTIFICATION_CLASS
+NOTIFY_NOTIFICATION_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>notify</FILE>
+notify_init
+notify_uninit
+notify_is_initted
+notify_get_app_name
+notify_get_server_caps
+notify_get_server_info
+</SECTION>
+

docs/reference/tmpl/libnotify-docs.sgml

@@ -0,0 +1,14 @@
+<?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">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>libgalago Reference Manual</title>
+  </bookinfo>
+
+  <chapter id='libnotify'>
+    <title>libnotify</title>
+    <xi:include href="xml/notify.sgml"/>
+    <xi:include href="xml/notify-notification.sgml"/>
+  </chapter>
+</book>

docs/reference/tmpl/notification.sgml

@@ -0,0 +1,274 @@
+<!-- ##### SECTION Title ##### -->
+NotifyNotification
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### MACRO NOTIFY_EXPIRES_DEFAULT ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO NOTIFY_EXPIRES_NEVER ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### STRUCT NotifyNotificationPrivate ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT NotifyNotification ##### -->
+<para>
+
+</para>
+
+@parent: 
+@priv: 
+
+<!-- ##### ENUM NotifyUrgency ##### -->
+<para>
+
+</para>
+
+@NOTIFY_URGENCY_LOW: 
+@NOTIFY_URGENCY_NORMAL: 
+@NOTIFY_URGENCY_CRITICAL: 
+
+<!-- ##### USER_FUNCTION NotifyActionCallback ##### -->
+<para>
+
+</para>
+
+@Param1: 
+@Param2: 
+@Param3: 
+
+
+<!-- ##### MACRO NOTIFY_ACTION_CALLBACK ##### -->
+<para>
+
+</para>
+
+@func: 
+
+
+<!-- ##### FUNCTION notify_notification_new ##### -->
+<para>
+
+</para>
+
+@summary: 
+@body: 
+@icon: 
+@attach: 
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_notification_new_with_status_icon ##### -->
+<para>
+
+</para>
+
+@summary: 
+@body: 
+@icon: 
+@status_icon: 
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_notification_update ##### -->
+<para>
+
+</para>
+
+@notification: 
+@summary: 
+@body: 
+@icon: 
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_notification_attach_to_widget ##### -->
+<para>
+
+</para>
+
+@notification: 
+@attach: 
+
+
+<!-- ##### FUNCTION notify_notification_attach_to_status_icon ##### -->
+<para>
+
+</para>
+
+@notification: 
+@status_icon: 
+
+
+<!-- ##### FUNCTION notify_notification_set_geometry_hints ##### -->
+<para>
+
+</para>
+
+@notification: 
+@screen: 
+@rect: 
+
+
+<!-- ##### FUNCTION notify_notification_show ##### -->
+<para>
+
+</para>
+
+@notification: 
+@error: 
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_notification_set_timeout ##### -->
+<para>
+
+</para>
+
+@notification: 
+@timeout: 
+
+
+<!-- ##### FUNCTION notify_notification_set_category ##### -->
+<para>
+
+</para>
+
+@notification: 
+@category: 
+
+
+<!-- ##### FUNCTION notify_notification_set_urgency ##### -->
+<para>
+
+</para>
+
+@notification: 
+@l: 
+
+
+<!-- ##### FUNCTION notify_notification_set_icon_from_pixbuf ##### -->
+<para>
+
+</para>
+
+@notification: 
+@icon: 
+
+
+<!-- ##### FUNCTION notify_notification_set_hint_int32 ##### -->
+<para>
+
+</para>
+
+@notification: 
+@key: 
+@value: 
+
+
+<!-- ##### FUNCTION notify_notification_set_hint_double ##### -->
+<para>
+
+</para>
+
+@notification: 
+@key: 
+@value: 
+
+
+<!-- ##### FUNCTION notify_notification_set_hint_string ##### -->
+<para>
+
+</para>
+
+@notification: 
+@key: 
+@value: 
+
+
+<!-- ##### FUNCTION notify_notification_set_hint_byte ##### -->
+<para>
+
+</para>
+
+@notification: 
+@key: 
+@value: 
+
+
+<!-- ##### FUNCTION notify_notification_set_hint_byte_array ##### -->
+<para>
+
+</para>
+
+@notification: 
+@key: 
+@value: 
+@len: 
+
+
+<!-- ##### FUNCTION notify_notification_clear_hints ##### -->
+<para>
+
+</para>
+
+@notification: 
+
+
+<!-- ##### FUNCTION notify_notification_add_action ##### -->
+<para>
+
+</para>
+
+@notification: 
+@action: 
+@label: 
+@callback: 
+@user_data: 
+@free_func: 
+
+
+<!-- ##### FUNCTION notify_notification_clear_actions ##### -->
+<para>
+
+</para>
+
+@notification: 
+
+
+<!-- ##### FUNCTION notify_notification_close ##### -->
+<para>
+
+</para>
+
+@notification: 
+@error: 
+@Returns: 
+
+

docs/reference/tmpl/notify.sgml

@@ -0,0 +1,71 @@
+<!-- ##### SECTION Title ##### -->
+notify
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### FUNCTION notify_init ##### -->
+<para>
+
+</para>
+
+@app_name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_uninit ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### FUNCTION notify_is_initted ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_get_app_name ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_get_server_caps ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION notify_get_server_info ##### -->
+<para>
+
+</para>
+
+@ret_name: 
+@ret_vendor: 
+@ret_version: 
+@ret_spec_version: 
+@Returns: 
+
+

libnotify/notification.c

@@ -460,6 +460,18 @@ _idle_check_updates(void *user_data)
 }
 #endif
 
+/**
+ * notify_notification_new:
+ * @summary: The required summary text.
+ * @body: The optional body text.
+ * @icon: The optional icon theme icon name or filename.
+ * @attach: The optional widget to attach to.
+ *
+ * Creates a new #NotifyNotification. The summary text is required, but
+ * all other parameters are optional.
+ *
+ * Returns: The new #NotifyNotification.
+ */
 NotifyNotification *
 notify_notification_new(const gchar *summary, const gchar *body,
 						const gchar *icon, GtkWidget *attach)
@@ -475,13 +487,29 @@ notify_notification_new(const gchar *summary, const gchar *body,
 }
 
 #ifdef HAVE_STATUS_ICON
+/**
+ * notify_notification_new_with_status_icon:
+ * @summary: The required summary text.
+ * @body: The optional body text.
+ * @icon: The optional icon theme icon name or filename.
+ * @status_icon: The required #GtkStatusIcon.
+ *
+ * Creates a new #NotifyNotification and attaches to a #GtkStatusIcon.
+ * The summary text and @status_icon is required, but all other parameters
+ * are optional.
+ *
+ * Returns: The new #NotifyNotification.
+ *
+ * Since: 0.4.1
+ */
 NotifyNotification *
 notify_notification_new_with_status_icon(const gchar *summary,
                                          const gchar *message,
                                          const gchar *icon,
                                          GtkStatusIcon *status_icon)
 {
-	g_return_val_if_fail(status_icon == NULL || GTK_IS_STATUS_ICON(status_icon), NULL);
+	g_return_val_if_fail(status_icon == NULL, NULL);
+	g_return_val_if_fail(GTK_IS_STATUS_ICON(status_icon), NULL);
 
 	return g_object_new(NOTIFY_TYPE_NOTIFICATION,
 						"summary", summary,
@@ -492,6 +520,19 @@ notify_notification_new_with_status_icon(const gchar *summary,
 }
 #endif /* HAVE_STATUS_ICON */
 
+/**
+ * notify_notification_update:
+ * @notification: The notification to update.
+ * @summary: The new required summary text.
+ * @body: The optional body text.
+ * @icon: The optional icon theme icon name or filename.
+ *
+ * Updates the notification text and icon. This won't send the update out
+ * and display it on the screen. For that, you will need to call
+ * notify_notification_show().
+ *
+ * Returns: %TRUE, unless an invalid parameter was passed.
+ */
 gboolean
 notify_notification_update(NotifyNotification *notification,
 						   const gchar *summary, const gchar *body,
@@ -529,6 +570,15 @@ notify_notification_update(NotifyNotification *notification,
 	return TRUE;
 }
 
+/**
+ * notify_notification_attach_to_widget:
+ * @notification: The notification.
+ * @attach: The widget to attach to, or %NULL.
+ *
+ * Attaches the notification to a widget. This will set hints on the
+ * notification requesting that the notification point to the widget's
+ * location. If @attach is %NULL, the widget will be unset.
+ */
 void
 notify_notification_attach_to_widget(NotifyNotification *notification,
 									 GtkWidget *attach)
@@ -548,6 +598,17 @@ notify_notification_attach_to_widget(NotifyNotification *notification,
 }
 
 #ifdef HAVE_STATUS_ICON
+/**
+ * notify_notification_attach_to_status_icon:
+ * @notification: The notification.
+ * @status_icon: The #GtkStatusIcon to attach to, or %NULL.
+ *
+ * Attaches the notification to a #GtkStatusIcon. This will set hints on the
+ * notification requesting that the notification point to the status icon's
+ * location. If @status_icon is %NULL, the status icon will be unset.
+ *
+ * Since: 0.4.1
+ */
 void
 notify_notification_attach_to_status_icon(NotifyNotification *notification,
 										  GtkStatusIcon *status_icon)
@@ -591,8 +652,6 @@ notify_notification_set_geometry_hints(NotifyNotification *notification,
 
 	notify_notification_set_hint_int32(notification, "x", rect->x);
 	notify_notification_set_hint_int32(notification, "y", rect->y);
-	notify_notification_set_hint_int32(notification, "width", rect->width);
-	notify_notification_set_hint_int32(notification, "height", rect->height);
 
 	display_name = gdk_screen_make_display_name(screen);
 	notify_notification_set_hint_string(notification, "xdisplay", display_name);

libnotify/notification.h

@@ -84,18 +84,18 @@ typedef void (*NotifyActionCallback)(NotifyNotification *, gchar *, gpointer);
 GType notify_notification_get_type();
 
 NotifyNotification *notify_notification_new(const gchar *summary,
-											const gchar *message,
+											const gchar *body,
 											const gchar *icon,
 											GtkWidget *attach);
 #if GTK_CHECK_VERSION(2, 9, 2)
 NotifyNotification *notify_notification_new_with_status_icon(
-	const gchar *summary, const gchar *message,
+	const gchar *summary, const gchar *body,
 	const gchar *icon, GtkStatusIcon *status_icon);
 #endif
 
 gboolean notify_notification_update(NotifyNotification *notification,
 									const gchar *summary,
-									const gchar *message,
+									const gchar *body,
 									const gchar *icon);
 
 void notify_notification_attach_to_widget(NotifyNotification* notification,

libnotify/notify.c

@@ -39,6 +39,14 @@ static GList *_active_notifications = NULL;
 #  define format_func
 #endif
 
+/**
+ * notify_init:
+ * @app_name: The name of the application initializing libnotify.
+ *
+ * Initialized libnotify. This must be called before any other functions.
+ *
+ * Returns: %TRUE if successful, or %FALSE on error.
+ */
 gboolean
 notify_init(const char *app_name)
 {
@@ -88,12 +96,27 @@ notify_init(const char *app_name)
 	return TRUE;
 }
 
+/**
+ * notify_get_app_name:
+ *
+ * Gets the application name registered.
+ *
+ * Returns: The registered application name, passed to notify_init().
+ */
 const gchar *
 notify_get_app_name(void)
 {
 	return _app_name;
 }
 
+/**
+ * notify_uninit:
+ *
+ * Uninitialized libnotify.
+ *
+ * This should be called when the program no longer needs libnotify for
+ * the rest of its lifecycle, typically just before exitting.
+ */
 void
 notify_uninit(void)
 {
@@ -119,6 +142,13 @@ notify_uninit(void)
 	_initted = FALSE;
 }
 
+/**
+ * notify_is_initted:
+ *
+ * Gets whether or not libnotify is initialized.
+ *
+ * Returns: %TRUE if libnotify is initialized, or %FALSE otherwise.
+ */
 gboolean
 notify_is_initted(void)
 {
@@ -137,6 +167,13 @@ _notify_get_g_proxy(void)
 	return _proxy;
 }
 
+/**
+ * notify_get_server_caps:
+ *
+ * Queries the server for its capabilities and returns them in a #GList.
+ *
+ * Returns: A #GList of server capability strings.
+ */
 GList *
 notify_get_server_caps(void)
 {
@@ -166,6 +203,21 @@ notify_get_server_caps(void)
 	return result;
 }
 
+/**
+ * notify_get_server_info:
+ * @ret_name: The resulting server name.
+ * @ret_vendor: The resulting server vendor.
+ * @ret_version: The resulting server version.
+ * @ret_spec_version: The resulting version of the specification the server is
+ *                    compliant with.
+ *
+ * Queries the server for its information, specifically, the name, vendor,
+ * server version, and the version of the notifications specification that it
+ * is compliant with.
+ *
+ * Returns: %TRUE if successful, and the variables passed will be set. %FALSE
+ *          on failure.
+ */
 gboolean
 notify_get_server_info(char **ret_name, char **ret_vendor,
 					   char **ret_version, char **ret_spec_version)