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.koe...@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. _______________________________________________ Xfce4-commits mailing list Xfce4-commits@xfce.org https://mail.xfce.org/mailman/listinfo/xfce4-commits