[Xfce4-commits] [xfce/libxfce4ui] 03/03: Add GtkDoc checks
noreply at xfce.org
noreply at xfce.org
Sun Jun 11 06:06:55 CEST 2017
This is an automated email from the git hooks/post-receive script.
e r i c 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/libxfce4ui.
commit a9c88f86e9f8384fb441758c853792a66e5fead1
Author: Eric Koegel <eric.koegel at gmail.com>
Date: Sat Jun 10 15:44:37 2017 +0300
Add GtkDoc checks
We add a documentation check during make check or distcheck to
ensure new functions/objects added are properly added prior to
release. This patch also cleans up all the current warnings.
---
.gitignore | 11 +++++++++++
docs/Makefile.am | 14 +++++++++++++-
docs/libxfce4ui-docs.xml | 6 ++++++
libxfce4ui/libxfce4ui-config.c | 31 ++++++++++++++++++++++++++++++-
libxfce4ui/libxfce4ui-config.h.in | 33 +++++++++++++++++++++++++++++++++
libxfce4ui/xfce-dialogs.c | 16 ++++++++++++++--
libxfce4ui/xfce-dialogs.h | 17 +++++++++++++++++
libxfce4ui/xfce-gdk-extensions.c | 12 +++++++++++-
libxfce4ui/xfce-gtk-extensions.c | 18 ++++++++++++++----
libxfce4ui/xfce-sm-client.c | 8 ++++----
libxfce4ui/xfce-sm-client.h | 2 +-
libxfce4ui/xfce-spawn.c | 12 +++++++++++-
libxfce4ui/xfce-titled-dialog.c | 11 +++++++++++
libxfce4ui/xfce-titled-dialog.h | 5 +++++
14 files changed, 181 insertions(+), 15 deletions(-)
diff --git a/.gitignore b/.gitignore
index cfc8145..a383ecb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -80,3 +80,14 @@ tests/test-ui-gtk2
tests/test_ui_gtk2-test-ui.o
tests/test-ui-gtk3
tests/test_ui_gtk3-test-ui.o
+
+# files generated by make check
+docs/gtkdoc-check.log
+docs/gtkdoc-check.test
+docs/gtkdoc-check.trs
+docs/libxfce4ui-decl-list.txt.bak
+docs/libxfce4ui-decl.txt.bak
+docs/test-suite.log
+libxfce4ui/abicheck.sh.log
+libxfce4ui/abicheck.sh.trs
+libxfce4ui/test-suite.log
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 2453a54..c737565 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -29,7 +29,12 @@ CFILE_GLOB=$(top_srcdir)/libxfce4ui/*.c
IGNORE_HFILES= \
libxfce4ui.h \
libxfce4ui-private.h \
- xfce-heading.h
+ xfce-heading.h \
+ libxfce4ui-enum-types.h \
+ libxfce4ui-alias.h \
+ stamp-libxfce4ui-marshal.h \
+ libxfce4ui-marshal.h \
+ libxfce4ui-resources.h
# Extra files to add when scanning (relative to $srcdir)
EXTRA_HFILES=
@@ -61,6 +66,13 @@ include $(top_srcdir)/gtk-doc.make
EXTRA_DIST += \
version.xml.in
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = \
+ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+TESTS = $(GTKDOC_CHECK)
+endif
+
# required for gtk-doc
dist-hook: all
diff --git a/docs/libxfce4ui-docs.xml b/docs/libxfce4ui-docs.xml
index 7cc307a..60a2f12 100644
--- a/docs/libxfce4ui-docs.xml
+++ b/docs/libxfce4ui-docs.xml
@@ -8,6 +8,9 @@
<!ENTITY xfce-dialogs SYSTEM "xml/xfce-dialogs.xml">
<!ENTITY xfce-titled-dialog SYSTEM "xml/xfce-titled-dialog.xml">
<!ENTITY xfce-sm-client SYSTEM "xml/xfce-sm-client.xml">
+<!ENTITY api-index-full SYSTEM "xml/api-index-full.xml">
+<!ENTITY annotation-glossary SYSTEM "xml/annotation-glossary.xml">
+<!ENTITY api-index-deprecated SYSTEM "xml/api-index-deprecated.xml">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY date "May 2017">
@@ -79,6 +82,9 @@
<index>
<title>Index</title>
+ &api-index-full;
+ &annotation-glossary;
+ &api-index-deprecated;
</index>
</book>
diff --git a/libxfce4ui/libxfce4ui-config.c b/libxfce4ui/libxfce4ui-config.c
index 28c9aee..c596a89 100644
--- a/libxfce4ui/libxfce4ui-config.c
+++ b/libxfce4ui/libxfce4ui-config.c
@@ -17,6 +17,16 @@
* MA 02110-1301 USA
*/
+/**
+ * SECTION:libxfce4ui-config
+ * @title: libxfce4ui config
+ * @short_description: libxfce4ui config macros
+ * @stability: Stable
+ * @include: libxfce4ui/libxfce4ui.h
+ *
+ * Variables and functions to check the Libxfce4ui version.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -25,9 +35,28 @@
#include <libxfce4ui/libxfce4ui-alias.h>
-
+/**
+ * libxfce4ui_major_version:
+ *
+ * A constat that evaluates to the major version of libxfce4ui.
+ *
+ */
const guint libxfce4ui_major_version = LIBXFCE4UI_MAJOR_VERSION;
+
+/**
+ * libxfce4ui_minor_version:
+ *
+ * A constat that evaluates to the minor version of libxfce4ui.
+ *
+ */
const guint libxfce4ui_minor_version = LIBXFCE4UI_MINOR_VERSION;
+
+/**
+ * libxfce4ui_micro_version:
+ *
+ * A constat that evaluates to the micro version of libxfce4ui.
+ *
+ */
const guint libxfce4ui_micro_version = LIBXFCE4UI_MICRO_VERSION;
diff --git a/libxfce4ui/libxfce4ui-config.h.in b/libxfce4ui/libxfce4ui-config.h.in
index 21359e8..a99bfba 100644
--- a/libxfce4ui/libxfce4ui-config.h.in
+++ b/libxfce4ui/libxfce4ui-config.h.in
@@ -28,10 +28,43 @@
G_BEGIN_DECLS
+/**
+ * LIBXFCE4UI_MAJOR_VERSION:
+ *
+ * A macro that evaluates to the major version of libxfce4ui, in a format
+ * that can be used by the C pre-processor.
+ *
+ */
#define LIBXFCE4UI_MAJOR_VERSION (@LIBXFCE4UI_VERSION_MAJOR@)
+
+/**
+ * LIBXFCE4UI_MINOR_VERSION:
+ *
+ * A macro that evaluates to the minor version of libxfce4ui, in a format
+ * that can be used by the C pre-processor.
+ *
+ */
#define LIBXFCE4UI_MINOR_VERSION (@LIBXFCE4UI_VERSION_MINOR@)
+
+/**
+ * LIBXFCE4UI_MICRO_VERSION:
+ *
+ * A macro that evaluates to the micro version of libxfce4ui, in a format
+ * that can be used by the C pre-processor.
+ *
+ */
#define LIBXFCE4UI_MICRO_VERSION (@LIBXFCE4UI_VERSION_MICRO@)
+/**
+ * LIBXFCE4UI_CHECK_VERSION:
+ * @major : The major version of the library, i.e. @LIBXFCE4UI_VERSION_MAJOR@
+ * @minor : The minor version of the library, i.e. @LIBXFCE4UI_VERSION_MINOR@
+ * @micro : The micro release of the library, i.e. @LIBXFCE4UI_VERSION_MICRO@
+ *
+ * A macro to compare libxfce4ui versions to determine if a particular
+ * function is available.
+ *
+ */
#define LIBXFCE4UI_CHECK_VERSION(major,minor,micro) \
(LIBXFCE4UI_MAJOR_VERSION > (major) \
|| (LIBXFCE4UI_MAJOR_VERSION == (major) \
diff --git a/libxfce4ui/xfce-dialogs.c b/libxfce4ui/xfce-dialogs.c
index 186e5e8..a95fb65 100644
--- a/libxfce4ui/xfce-dialogs.c
+++ b/libxfce4ui/xfce-dialogs.c
@@ -18,6 +18,18 @@
* MA 02110-1301 USA
*/
+/**
+ * SECTION:xfce-dialogs
+ * @title: XfceDialogs
+ * @short_description: A collection of helper dialogs
+ * @stability: Stable
+ * @include: libxfce4ui/libxfce4ui.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.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -533,7 +545,7 @@ xfce_dialog_confirm (GtkWindow *parent,
* See xfce_message_dialog_new(), this version takes a va_list for
* language bindings to use.
*
- * Returns: A new #GtkMessageDialog.
+ * Returns: (transfer full): A new #GtkMessageDialog.
**/
GtkWidget *
xfce_message_dialog_new_valist (GtkWindow *parent,
@@ -871,7 +883,7 @@ xfce_message_dialog_new_valist (GtkWindow *parent,
* </programlisting>
* </example>
*
- * Return value: A new #GtkMessageDialog.
+ * Return value: (transfer full): A new #GtkMessageDialog.
**/
GtkWidget *
xfce_message_dialog_new (GtkWindow *parent,
diff --git a/libxfce4ui/xfce-dialogs.h b/libxfce4ui/xfce-dialogs.h
index e27ddd0..88c5234 100644
--- a/libxfce4ui/xfce-dialogs.h
+++ b/libxfce4ui/xfce-dialogs.h
@@ -28,7 +28,24 @@
G_BEGIN_DECLS
+/**
+ * XFCE_BUTTON_TYPE_MIXED:
+ *
+ * This allows you to easily create mixed buttons in a dialog.
+ * param1 is used for the stock_id, param2 for the label and
+ * param3 for the response_id. See also xfce_gtk_button_new_mixed().
+ *
+ **/
#define XFCE_BUTTON_TYPE_MIXED "button-mixed"
+
+/**
+ * XFCE_BUTTON_TYPE_PIXBUF:
+ *
+ * Creates a button with the #GdkPixbuf as button icon.
+ * param1 is the #GdkPixuf, param2 for the label and
+ * param3 for the response_id.
+ *
+ **/
#define XFCE_BUTTON_TYPE_PIXBUF "button-pixbuf"
void xfce_dialog_show_help (GtkWindow *parent,
diff --git a/libxfce4ui/xfce-gdk-extensions.c b/libxfce4ui/xfce-gdk-extensions.c
index 7cfd8a1..260f38b 100644
--- a/libxfce4ui/xfce-gdk-extensions.c
+++ b/libxfce4ui/xfce-gdk-extensions.c
@@ -18,6 +18,16 @@
* MA 02110-1301 USA
*/
+/**
+ * SECTION:xfce-gdk-extensions
+ * @title: Gdk Extensions
+ * @short_description: various extensions to Gdk
+ * @stability: Stable
+ * @include: libxfce4ui/libxfce4ui.h
+ *
+ * Common used functions that are not provided by the Gdk or Gdk-pixbuf library.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -44,7 +54,7 @@
* currently contains the pointer. If no active screen was found, the
* default #GdkScreen is returned.
*
- * Return value: the currently active #GdkScreen.
+ * Return value: (transfer full): the currently active #GdkScreen.
**/
GdkScreen *
xfce_gdk_screen_get_active (gint *monitor_return)
diff --git a/libxfce4ui/xfce-gtk-extensions.c b/libxfce4ui/xfce-gtk-extensions.c
index 20ea464..224136b 100644
--- a/libxfce4ui/xfce-gtk-extensions.c
+++ b/libxfce4ui/xfce-gtk-extensions.c
@@ -17,6 +17,16 @@
* MA 02110-1301 USA
*/
+/**
+ * SECTION:xfce-gtk-extensions
+ * @title: Gtk Extensions
+ * @short_description: various extensions to Gtk+
+ * @stability: Stable
+ * @include: libxfce4ui/libxfce4ui.h
+ *
+ * Common used functions for GtkWidget's that are not provided by the Gtk+ library
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -47,7 +57,7 @@
* when @label is %NULL a stock button will be created. This behaviour
* is added for xfce_message_dialog_new().
*
- * Return value: the newly created #GtkButton widget.
+ * Return value: (transfer full): the newly created #GtkButton widget.
**/
GtkWidget *
xfce_gtk_button_new_mixed (const gchar *stock_id,
@@ -102,7 +112,7 @@ xfce_gtk_button_new_mixed (const gchar *stock_id,
*
* See also: xfce_gtk_frame_box_new_with_content().
*
- * Return value: the newly created #GtkFrame widget.
+ * Return value: (transfer full): the newly created #GtkFrame widget.
**/
GtkWidget *
xfce_gtk_frame_box_new (const gchar *label,
@@ -152,7 +162,7 @@ xfce_gtk_frame_box_new (const gchar *label,
* Creates a widget with xfce_gtk_frame_box_new() and adds the
* @content #GtkWidget to the frame.
*
- * Return value: the newly created #GtkFrame widget.
+ * Return value: (transfer full): the newly created #GtkFrame widget.
**/
GtkWidget *
xfce_gtk_frame_box_new_with_content (const gchar *label,
@@ -205,7 +215,7 @@ xfce_gtk_window_center_on_active_screen (GtkWindow *window)
* @menu: a #GtkMenu.
* @parent_menu_shell: the menu shell containing the triggering menu item, or %NULL.
* @parent_menu_item: the menu item whose activation triggered the popup, or %NULL.
- * @func: a user supplied function used to position the menu, or %NULL.
+ * @func: (scope call): a user supplied function used to position the menu, or %NULL.
* @data: user supplied data to be passed to func.
* @button: the mouse button which was pressed to initiate the event.
* @activate_time: the time at which the activation event occurred.
diff --git a/libxfce4ui/xfce-sm-client.c b/libxfce4ui/xfce-sm-client.c
index 76a1b70..a053d14 100644
--- a/libxfce4ui/xfce-sm-client.c
+++ b/libxfce4ui/xfce-sm-client.c
@@ -22,7 +22,7 @@
* SECTION:xfce-sm-client
* @title: XfceSMClient
* @short_description: Session management client
- * @stability: Unstable
+ * @stability: Stable
* @include: libxfce4ui/libxfce4ui.h
*
* #XfceSMClient is a session management client that speaks the X Session
@@ -1458,7 +1458,7 @@ xfce_sm_client_get_option_group(gint argc,
* this function or one of the xfce_sm_client_new_*() functions,
* this will return the same instance.
*
- * Returns: A new or existing #XfceSMClient
+ * Returns: (transfer full): A new or existing #XfceSMClient
**/
XfceSMClient *
xfce_sm_client_get(void)
@@ -1488,7 +1488,7 @@ xfce_sm_client_get(void)
* it is recommended that you use xfce_sm_client_get_option_group()
* and xfce_sm_client_get() instead.
*
- * Returns: A new #XfceSMClient instance
+ * Returns: (transfer full): A new #XfceSMClient instance
**/
XfceSMClient *
xfce_sm_client_get_with_argv(gint argc,
@@ -1525,7 +1525,7 @@ xfce_sm_client_get_with_argv(gint argc,
* if you are using Gtk or Glib's command-line option parser,
* xfce_sm_client_get_option_group() and xfce_sm_client_get() instead.
*
- * Returns: A new #XfceSMClient instance
+ * Returns: (transfer full): A new #XfceSMClient instance
**/
XfceSMClient *
xfce_sm_client_get_full(XfceSMClientRestartStyle restart_style,
diff --git a/libxfce4ui/xfce-sm-client.h b/libxfce4ui/xfce-sm-client.h
index 3158333..2f0a874 100644
--- a/libxfce4ui/xfce-sm-client.h
+++ b/libxfce4ui/xfce-sm-client.h
@@ -44,7 +44,7 @@
/**
* XfceSmCLientErrorEnum:
- * @G_IO_ERROR_FAILED: Failed to connect to the session manager.
+ * @XFCE_SM_CLIENT_ERROR_FAILED: Failed to connect to the session manager.
* @XFCE_SM_CLIENT_ERROR_INVALID_CLIENT: Session does not have a valid client id.
*
* Error codes returned by XfceSmCLient functions.
diff --git a/libxfce4ui/xfce-spawn.c b/libxfce4ui/xfce-spawn.c
index 6e9f33f..ced3c89 100644
--- a/libxfce4ui/xfce-spawn.c
+++ b/libxfce4ui/xfce-spawn.c
@@ -18,6 +18,16 @@
* MA 02110-1301 USA
*/
+/**
+ * SECTION:xfce-spawn
+ * @title: Spawn
+ * @short_description: spawn a command with startup notification
+ * @stability: Stable
+ * @include: libxfce4ui/libxfce4ui.h
+ *
+ * Functions to spawn a command with startup notification support.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
@@ -251,7 +261,7 @@ xfce_spawn_get_active_workspace_number (GdkScreen *screen)
/**
- * xfce_spawn_on_screen_with_closure:
+ * xfce_spawn_on_screen_with_child_watch:
* @screen : a #GdkScreen or %NULL to use the active screen,
* see xfce_gdk_screen_get_active().
* @working_directory : child's current working directory or %NULL to
diff --git a/libxfce4ui/xfce-titled-dialog.c b/libxfce4ui/xfce-titled-dialog.c
index 1abbd45..0d948d9 100644
--- a/libxfce4ui/xfce-titled-dialog.c
+++ b/libxfce4ui/xfce-titled-dialog.c
@@ -17,6 +17,17 @@
* MA 02110-1301 USA
*/
+/**
+ * SECTION:xfce-titled-dialog
+ * @title: XfceTitledDialog
+ * @short_description: A titled dialog window
+ * @stability: Stable
+ * @include: libxfce4ui/libxfce4ui.h
+ *
+ * #XfceTitledDialog is a titled dialog window supporting an optional
+ * subtitle and mixed or pixbuf buttons.
+ **/
+
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif
diff --git a/libxfce4ui/xfce-titled-dialog.h b/libxfce4ui/xfce-titled-dialog.h
index e78f691..edd61b8 100644
--- a/libxfce4ui/xfce-titled-dialog.h
+++ b/libxfce4ui/xfce-titled-dialog.h
@@ -53,6 +53,11 @@ struct _XfceTitledDialogClass
void (*reserved5) (void);
};
+/**
+ * XfceTitledDialog:
+ *
+ * An opaque struct with only private fields.
+ **/
struct _XfceTitledDialog
{
/*< private >*/
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Xfce4-commits
mailing list