[Xfce4-commits] [xfce/libxfce4util] 02/04: Migrate away from sgml templates for documentation
noreply at xfce.org
noreply at xfce.org
Sun Dec 10 13:47:01 CET 2017
This is an automated email from the git hooks/post-receive script.
s k u n n y k p u s h e d a c o m m i t t o b r a n c h m a s t e r
in repository xfce/libxfce4util.
commit 9b9124ec8d17254ea2e50f02384abae471860514
Author: Romain B <skunnyk at alteroot.org>
Date: Sat Dec 9 18:38:39 2017 +0100
Migrate away from sgml templates for documentation
---
libxfce4util/libxfce4util-config.c | 9 ++++
libxfce4util/xfce-fileutils.c | 9 ++++
libxfce4util/xfce-generics.h | 79 ++++++++++++++++++++++++++++++++
libxfce4util/xfce-i18n.c | 11 +++++
libxfce4util/xfce-kiosk.c | 8 ++++
libxfce4util/xfce-license.c | 6 +++
libxfce4util/xfce-miscutils.c | 8 ++++
libxfce4util/xfce-posix-signal-handler.c | 13 ++++++
libxfce4util/xfce-posix-signal-handler.h | 6 +++
libxfce4util/xfce-rc.c | 16 +++++++
libxfce4util/xfce-resource.c | 8 ++++
libxfce4util/xfce-utf8.c | 9 ++++
12 files changed, 182 insertions(+)
diff --git a/libxfce4util/libxfce4util-config.c b/libxfce4util/libxfce4util-config.c
index a928181..425f785 100644
--- a/libxfce4util/libxfce4util-config.c
+++ b/libxfce4util/libxfce4util-config.c
@@ -19,6 +19,15 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: libxfce4util-config
+ * @title: Version Information
+ * @short_description: Variables and functions to check the libxfce4util version
+ * @see_also: https://developer.gnome.org/glib/stable/glib-Standard-Macros.html
+ *
+ * These macros provide a few commonly-used features.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-fileutils.c b/libxfce4util/xfce-fileutils.c
index dd26849..7f6528b 100644
--- a/libxfce4util/xfce-fileutils.c
+++ b/libxfce4util/xfce-fileutils.c
@@ -19,6 +19,15 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-fileutils
+ * @title: File Utilities
+ * @short_description: miscellaneous file-related utility functions.
+ * @see_also: https://developer.gnome.org/glib/stable/glib-File-Utilities.html
+ *
+ * File Utilities
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-generics.h b/libxfce4util/xfce-generics.h
index b668ef0..4732899 100644
--- a/libxfce4util/xfce-generics.h
+++ b/libxfce4util/xfce-generics.h
@@ -19,6 +19,31 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION:xfce-generics
+ * @title: Xfce Generics
+ * @short_description: Generic data types and related functions.
+ * @stability: Stable
+ * @include: libxfce4util/libxfce4util.h
+ *
+ * Xfce-dialogs are a collection of helper dialogs to display
+ * the help dialog with link to the docs website, warning, info, and
+ * error dialogs and more.
+ *
+ * Using a generic stack
+ * |[<!-- language="C" -->
+ * typedef XFCE_GENERIC_STACK(int) IntStack;
+ * IntStack *stack = xfce_stack_new (IntStack);
+ * xfce_stack_push (stack, 0);
+ * xfce_stack_push (stack, 1);
+ * printf ("Top is %d\n", xfce_stack_top (stack));
+ * xfce_stack_pop (stack);
+ * printf ("Top is %d\n", xfce_stack_top (stack));
+ * xfce_stack_free (stack);
+ * ]|
+ *
+ */
+
#if !defined(LIBXFCE4UTIL_INSIDE_LIBXFCE4UTIL_H) && !defined(LIBXFCE4UTIL_COMPILATION)
#error "Only <libxfce4util/libxfce4util.h> can be included directly, this file may disappear or change contents"
#endif
@@ -30,6 +55,22 @@
G_BEGIN_DECLS
+/**
+ * XFCE_GENERIC_STACK:
+ * @Type: Data type of the elements that should be handled by the stack. Can be any valid data type from simple int's to complex structures.
+ *
+ *
+ * This macro is used to create a new stack data type which elements are of
+ * @Type. For example, to create a stack type that handles elements of type
+ * %double, you'd write the following
+ *
+ * |[<!-- language="C" -->
+ * typedef XFCE_GENERIC_STACK(double) MyDoubleStack;
+ * ]|
+ * and furtheron refer to your stack type as %MyDoubleStack.
+ *
+ */
+
#define XFCE_GENERIC_STACK(Type) \
struct \
{ \
@@ -39,7 +80,22 @@ G_BEGIN_DECLS
}
+/**
+ * xfce_stack_new:
+ * @StackType: Type of stack declared with #XFCE_GENERIC_STACK.
+ *
+ * Creates a new instance of @StackType and returns a pointer to the newly
+ * created instance. For example, imagine you declared a type %MyDoubleStack
+ * as shown above, you can instantiate this type with
+ *
+ * |[<!-- language="C" -->
+ * MyDoubleStack *my_stack = xfce_stack_new (MyDoubleStack);
+ * ]|
+ *
+ */
+
#ifdef __GNUC__
+
#define xfce_stack_new(StackType) \
({ \
StackType *stack; \
@@ -67,6 +123,14 @@ xfce_stack_alloc (gsize element_size)
#endif
+/**
+ * xfce_stack_free:
+ * @stack: A stack object.
+ *
+ * Frees a stack, that was allocated using #xfce_stack_new.
+ *
+ */
+
#define xfce_stack_free(stack) \
G_STMT_START \
{ \
@@ -75,6 +139,11 @@ xfce_stack_alloc (gsize element_size)
} \
G_STMT_END
+/**
+ * xfce_stack_top:
+ *
+ * Removes the top element from @stack.
+ */
#ifdef __GNUC__
#define xfce_stack_top(stack) \
@@ -86,6 +155,11 @@ xfce_stack_alloc (gsize element_size)
#define xfce_stack_top(stack) ((stack)->elements[(stack)->top])
#endif
+/**
+ * xfce_stack_pop:
+ *
+ * Removes the top element from @stack.
+ */
#define xfce_stack_pop(stack) \
G_STMT_START \
@@ -95,6 +169,11 @@ xfce_stack_alloc (gsize element_size)
} \
G_STMT_END
+/**
+ * xfce_stack_push:
+ *
+ * Pushes a new @value on top of @stack.
+ */
#define xfce_stack_push(stack, value) \
G_STMT_START \
diff --git a/libxfce4util/xfce-i18n.c b/libxfce4util/xfce-i18n.c
index 83468c1..e79b726 100644
--- a/libxfce4util/xfce-i18n.c
+++ b/libxfce4util/xfce-i18n.c
@@ -20,6 +20,17 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-i18n
+ * @title: Internationalization
+ * @short_description: Internationalization and Localization Support Functions
+ * @see_also: https://developer.gnome.org/glib/stable/glib-I18N.html
+ *
+ * Provides functions to aid application developers making their software
+ * localizable. It extends the basic internationalization support provided
+ * by GLib 2.4 (and newer).
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-kiosk.c b/libxfce4util/xfce-kiosk.c
index 24feb4d..c3f0add 100644
--- a/libxfce4util/xfce-kiosk.c
+++ b/libxfce4util/xfce-kiosk.c
@@ -19,6 +19,14 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-kiosk
+ * @title: Xfce Kiosk functions
+ * @short_description: Xfce Kiosk mode support functions.
+ *
+ * This module provides a simple Kiosk mode for Xfce.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-license.c b/libxfce4util/xfce-license.c
index cb7868e..4f48f50 100644
--- a/libxfce4util/xfce-license.c
+++ b/libxfce4util/xfce-license.c
@@ -19,6 +19,12 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-license
+ * @title: Software Licenses
+ * @short_description: Software Licenses
+ *
+ */
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-miscutils.c b/libxfce4util/xfce-miscutils.c
index 27b4af8..02f0f09 100644
--- a/libxfce4util/xfce-miscutils.c
+++ b/libxfce4util/xfce-miscutils.c
@@ -19,6 +19,14 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-miscutils
+ * @title: Miscellaneous Utilities
+ * @short_description: miscellaneous file-related utility functions.
+ *
+ * Miscellaneous file-related utility functions.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-posix-signal-handler.c b/libxfce4util/xfce-posix-signal-handler.c
index 425519e..be7bafd 100644
--- a/libxfce4util/xfce-posix-signal-handler.c
+++ b/libxfce4util/xfce-posix-signal-handler.c
@@ -17,6 +17,19 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-posix-signal-handler
+ * @title: POSIX Signal Handling
+ * @short_description: a callback system for handling POSIX signals safely
+ *
+ * Due to reentrancy issues, there is a restricted set of functions/syscalls
+ * that are allowed to be performed inside a POSIX signal handler. In
+ * general, it's safer to defer any signal-related processing until after the
+ * signal handler has run. The functionality in this module automatically
+ * handles this, and allows you to set a handler function (with optional user
+ * data) for any signal.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-posix-signal-handler.h b/libxfce4util/xfce-posix-signal-handler.h
index 3c1d4d1..20a2b7e 100644
--- a/libxfce4util/xfce-posix-signal-handler.h
+++ b/libxfce4util/xfce-posix-signal-handler.h
@@ -28,6 +28,12 @@
G_BEGIN_DECLS
+/**
+ * XfcePosixSignalHandler:
+ * @signal: The signal that was caught.
+ * @user_data: The @user_data parameter passed when the handler was registered.
+ */
+
typedef void (*XfcePosixSignalHandler)(gint signal, gpointer user_data);
gboolean xfce_posix_signal_handler_init(GError **error);
diff --git a/libxfce4util/xfce-rc.c b/libxfce4util/xfce-rc.c
index 47685d0..bd6402a 100644
--- a/libxfce4util/xfce-rc.c
+++ b/libxfce4util/xfce-rc.c
@@ -19,6 +19,22 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-rc
+ * @title: Resource Config File Support
+ * @short_description: functions for reading and writing resource config files.
+ *
+ * Provides support for parsing INI-style resource config files like used by for
+ * example KDE and some Xfce components (like xfwm4, who uses rc files for the
+ * themes).
+ *
+ * The parser itself is optimized for high-performance using memory and string chunks
+ * to reduce the time spent looking for heap memory (a nice side effect of this is the
+ * reduced heap corruption). But due to this fact, an #XfceRc object might consume quite
+ * a lot of memory after some time of usage. Therefore you should close an #XfceRc object
+ * as soon as possible after loading configuration data from the object.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-resource.c b/libxfce4util/xfce-resource.c
index c4663d3..9ae7d1b 100644
--- a/libxfce4util/xfce-resource.c
+++ b/libxfce4util/xfce-resource.c
@@ -19,6 +19,14 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-resource
+ * @title: Resource lookup functions
+ * @short_description: Resource lookup functions
+ *
+ * Resource lookup functions
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4util/xfce-utf8.c b/libxfce4util/xfce-utf8.c
index 059ca1d..8ea6860 100644
--- a/libxfce4util/xfce-utf8.c
+++ b/libxfce4util/xfce-utf8.c
@@ -20,6 +20,15 @@
* Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION: xfce-utf8
+ * @title: Unicode Manipulation
+ * @short_description: functions operating on Unicode characters and UTF-8 strings.
+ * @see_also: https://developer.gnome.org/glib/stable/glib-Unicode-Manipulation.html
+ *
+ * Functions operating on Unicode characters and UTF-8 strings.
+ */
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Xfce4-commits
mailing list