jcarr
/
libnotify
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add some gtk-doc documentation.

This commit is contained in:
Christian Hammond 2006-06-06 07:14:42 +00:00
parent d986aaf233
commit cc13b1892f
17 changed files with 669 additions and 1094 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
ChangeLog
View File

@ -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:

1079
Doxyfile.in
View File

File diff suppressed because it is too large Load Diff

4
Makefile.am
View File

@ -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

9
autogen.sh
View File

@ -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"

18
configure.ac
View File

@ -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_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
LIBGALAGO_VERSION=$LIBGALAGO_VERSION.$LIBGALAGO_DEVEL_VERSION
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

5
docs/Makefile.am Normal file
View File

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

81
docs/reference/Makefile.am Normal file
View File

@ -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 +=

14
docs/reference/libnotify-docs.sgml Normal file
View File

@ -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>

0
docs/reference/libnotify-overrides.txt Normal file
View File

50
docs/reference/libnotify-sections.txt Normal file
View File

@ -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>

14
docs/reference/tmpl/libnotify-docs.sgml Normal file
View File

@ -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>

0
docs/reference/tmpl/libnotify-unused.sgml Normal file
View File

274
docs/reference/tmpl/notification.sgml Normal file
View File

@ -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:

71
docs/reference/tmpl/notify.sgml Normal file
View File

@ -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:

65
libnotify/notification.c
View File

@ -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);

6
libnotify/notification.h
View File

@ -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,

52
libnotify/notify.c
View File

@ -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)