GNOME.org
 

[devhelp/wip/tintou/gtk-doc] Enable GTK-Doc on the project

commit 26b6ada99d4e82c45e85a9c3958e78f0056c3a30
Author: Corentin Noël <corentin elementary io>
Date:   Mon Oct 24 00:27:41 2016 +0200

    Enable GTK-Doc on the project

 Makefile.am                |    2 +-
 autogen.sh                 |    2 +
 configure.ac               |    6 ++-
 docs/Makefile.am           |    1 +
 docs/reference/Makefile.am |   88 ++++++++++++++++++++++++++++++++++++++++++++
 src/dh-error.h             |   14 +++++++
 src/dh-link.h              |   20 ++++++++++
 src/dh-preferences.h       |    2 +-
 src/dh-settings.h          |   13 ++++--
 src/dh-sidebar.h           |    5 ++
 src/dh-window.h            |   12 +++++-
 11 files changed, 157 insertions(+), 8 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index 000c27e..414b36d 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,6 @@
 ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
 
-SUBDIRS = po src data misc contrib
+SUBDIRS = po src data misc contrib docs
 
 EXTRA_DIST = autogen.sh
 
diff --git a/autogen.sh b/autogen.sh
index 9b42897..22431ac 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -17,4 +17,6 @@ which gnome-autogen.sh || {
 
 git submodule update --init --recursive
 
+gtkdocize || exit 1
+
 . gnome-autogen.sh
diff --git a/configure.ac b/configure.ac
index 5768770..36540da 100644
--- a/configure.ac
+++ b/configure.ac
@@ -22,7 +22,7 @@ AC_CONFIG_SRCDIR(src/dh-main.c)
 AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_AUX_DIR([build-aux])
 
-AM_INIT_AUTOMAKE([1.11 -Wall foreign no-define tar-ustar no-dist-gzip dist-xz])
+AM_INIT_AUTOMAKE([1.11 -Wall foreign no-define tar-ustar no-dist-gzip dist-xz -Wno-portability])
 
 # Support silent build rules, requires at least automake-1.11. Disable
 # by either passing --disable-silent-rules to configure or passing V=1
@@ -89,6 +89,8 @@ AC_PATH_PROG(GLIB_MKENUMS, glib-mkenums)
 
 AM_PATH_PYTHON([2.3],[],[no])
 
+GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
+
 AC_CONFIG_FILES([
 Makefile
 po/Makefile.in
@@ -101,6 +103,8 @@ data/dtd/Makefile
 misc/Makefile
 misc/gedit-plugin/Makefile
 contrib/Makefile
+docs/Makefile
+docs/reference/Makefile
 ])
 
 AC_OUTPUT
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..f3ddc22
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = reference
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644
index 0000000..116a4ea
--- /dev/null
+++ b/docs/reference/Makefile.am
@@ -0,0 +1,88 @@
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=devhelp
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+DOC_MODULE_VERSION=3
+
+# The top-level XML file.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# Directories containing the source code.
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
+DOC_SOURCE_DIR=$(top_srcdir)/src
+
+# Extra options to pass to gtkdoc-scangobj. Normally not needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=--rebuild-types
+
+# Extra options to supply to gtkdoc-mkdb
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS=--xml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Normally not 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)/src/*.h
+CFILE_GLOB=$(top_srcdir)/src/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
+IGNORE_HFILES=
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.xml building.xml changes-2.0.xml
+content_files=
+
+# Files where gtk-doc abbrevations (#GtkWidget) are expanded
+# e.g. expand_content_files=running.xml
+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. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS= \
+       -I$(top_srcdir) \
+       -I$(top_builddir) \
+       -I$(top_builddir)/src \
+       $(LIBDEVHELP_CFLAGS) \
+       $(NULL)
+
+GTKDOC_LIBS= \
+       $(top_builddir)/src/libdevhelp-3.la \
+       $(LIBDEVHELP_LIBS) \
+       $(NULL)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+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
diff --git a/src/dh-error.h b/src/dh-error.h
index add07e8..d080008 100644
--- a/src/dh-error.h
+++ b/src/dh-error.h
@@ -24,8 +24,22 @@
 
 G_BEGIN_DECLS
 
+/**
+ * DH_ERROR:
+ *
+ * Error domain for DhParser errors
+ **/
 #define DH_ERROR dh_error_quark ()
 
+/**
+ * DhError:
+ * @DH_ERROR_FILE_NOT_FOUND:  Requested file did not exist
+ * @DH_ERROR_MALFORMED_BOOK: Referred book is invalid
+ * @DH_ERROR_INVALID_BOOK_TYPE: Referred book has an invalid type
+ * @DH_ERROR_INTERNAL_ERROR: An internal error occured
+ *
+ * Error codes returned the parser.
+ */
 typedef enum {
         DH_ERROR_FILE_NOT_FOUND,
         DH_ERROR_MALFORMED_BOOK,
diff --git a/src/dh-link.h b/src/dh-link.h
index 21c1625..b2806d8 100644
--- a/src/dh-link.h
+++ b/src/dh-link.h
@@ -22,6 +22,21 @@
 
 #include <glib-object.h>
 
+/**
+ * DhLinkType:
+ * @DH_LINK_TYPE_BOOK: a book
+ * @DH_LINK_TYPE_PAGE: a page
+ * @DH_LINK_TYPE_KEYWORD: a keyword
+ * @DH_LINK_TYPE_FUNCTION: a function
+ * @DH_LINK_TYPE_STRUCT: a struct
+ * @DH_LINK_TYPE_MACRO: a macro
+ * @DH_LINK_TYPE_ENUM: an enum
+ * @DH_LINK_TYPE_TYPEDEF: a typedef
+ * @DH_LINK_TYPE_PROPERTY: a property
+ * @DH_LINK_TYPE_SIGNAL: a signal
+ *
+ * The type of the content the link points to.
+ */
 typedef enum {
         DH_LINK_TYPE_BOOK,
         DH_LINK_TYPE_PAGE,
@@ -35,6 +50,11 @@ typedef enum {
         DH_LINK_TYPE_SIGNAL
 } DhLinkType;
 
+/**
+ * DhLinkFlags:
+ * @DH_LINK_FLAGS_NONE: no flag set
+ * @DH_LINK_FLAGS_DEPRECATED: deprecated link
+ */
 typedef enum {
         DH_LINK_FLAGS_NONE       = 0,
         DH_LINK_FLAGS_DEPRECATED = 1 << 0
diff --git a/src/dh-preferences.h b/src/dh-preferences.h
index 5517940..d3001bc 100644
--- a/src/dh-preferences.h
+++ b/src/dh-preferences.h
@@ -37,7 +37,7 @@ typedef struct _DhPreferencesClass        DhPreferencesClass;
 
 struct _DhPreferences
 {
-        GtkDialog parent;
+        GtkDialog parent_instance;
 };
 
 struct _DhPreferencesClass
diff --git a/src/dh-settings.h b/src/dh-settings.h
index dd3dd44..cdddf23 100644
--- a/src/dh-settings.h
+++ b/src/dh-settings.h
@@ -38,14 +38,19 @@ typedef struct _DhSettingsPrivate DhSettingsPrivate;
 
 
 struct _DhSettings{
-        GObject parent;
-        /*<private>*/
+        GObject parent_instance;
+        /*< private >*/
         DhSettingsPrivate *priv;
 };
 
+/**
+ * DhSettingsClass:
+ * @parent_class: The parent class.
+ * @fonts_changed: Class handler for the #DhSettings::fonts-changed signal
+ */
 struct _DhSettingsClass{
-        GObjectClass parent;
-        /* Signals */
+        GObjectClass parent_class;
+        /*< public >*/
         void (*fonts_changed) (DhSettings *settings,
                                const gchar *font_name_fixed,
                                const gchar *font_name_variable);
diff --git a/src/dh-sidebar.h b/src/dh-sidebar.h
index f2a3749..bba0ac8 100644
--- a/src/dh-sidebar.h
+++ b/src/dh-sidebar.h
@@ -40,6 +40,11 @@ struct _DhSidebar {
         GtkBox            parent_instance;
 };
 
+/**
+ * DhSidebarClass:
+ * @parent_class: The parent class.
+ * @link_selected: Class handler for the #DhSidebar::link-selected signal
+ */
 struct _DhSidebarClass {
         GtkBoxClass parent_class;
 
diff --git a/src/dh-window.h b/src/dh-window.h
index 9a4e9fc..d4058ee 100644
--- a/src/dh-window.h
+++ b/src/dh-window.h
@@ -36,6 +36,11 @@ G_BEGIN_DECLS
 typedef struct _DhWindow       DhWindow;
 typedef struct _DhWindowClass  DhWindowClass;
 
+/**
+ * DhOpenLinkFlags:
+ * @DH_OPEN_LINK_NEW_WINDOW: Open the link in a new window
+ * @DH_OPEN_LINK_NEW_TAB: Open the link in a new tab
+ */
 typedef enum
 {
         DH_OPEN_LINK_NEW_WINDOW = 1 << 0,
@@ -46,10 +51,15 @@ struct _DhWindow {
         GtkApplicationWindow parent_instance;
 };
 
+/**
+ * DhWindowClass:
+ * @parent_class: The parent class.
+ * @open_link: Class handler for the #DhWindow::open-link signal
+ */
 struct _DhWindowClass {
         GtkApplicationWindowClass parent_class;
 
-        /* Signals */
+        /*< public >*/
         void (*open_link) (DhWindow        *window,
                            const char      *location,
                            DhOpenLinkFlags  flags);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]