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

From: Corentin Noël <corentinnoel src gnome org>
To: commits-list gnome org
Cc:
Subject: [devhelp/wip/tintou/gtk-doc] Enable GTK-Doc on the project
Date: Sat, 29 Oct 2016 15:43:53 +0000 (UTC)
commit 97b141c97b85261eb687d2d0bf1b6c28b6813485
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 ++++++++++++
 docs/reference/devhelp-docs.xml      |   51 +++++++
 docs/reference/devhelp-sections.txt  |  257 ++++++++++++++++++++++++++++++++++
 src/dh-error.h                       |   14 ++
 src/dh-link.h                        |   20 +++
 src/dh-settings.h                    |    9 +-
 src/dh-sidebar.h                     |    5 +
 src/dh-window.h                      |   10 ++
 12 files changed, 461 insertions(+), 4 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..a41e993
--- /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 = dh-enum-types.h dh-parser.h dh-preferences.h dh-resources.h dh-settings.h dh-util.h
+
+# 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/docs/reference/devhelp-docs.xml b/docs/reference/devhelp-docs.xml
new file mode 100644
index 0000000..ae5db4b
--- /dev/null
+++ b/docs/reference/devhelp-docs.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
+]>
+<book id="index">
+  <bookinfo>
+    <title>&package_name; Reference Manual</title>
+    <releaseinfo>
+      for &package_string;.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" 
url="http://developer.gnome.org/devhelp/index.html";>http://developer.gnome.org/devhelp/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>DevHelp</title>
+    <xi:include href="xml/init.xml"/>
+    <xi:include href="xml/dh-app.xml"/>
+    <xi:include href="xml/dh-assistant.xml"/>
+    <xi:include href="xml/dh-assistant-view.xml"/>
+    <xi:include href="xml/dh-book.xml"/>
+    <xi:include href="xml/dh-book-manager.xml"/>
+    <xi:include href="xml/dh-book-tree.xml"/>
+    <xi:include href="xml/dh-error.xml"/>
+    <xi:include href="xml/dh-keyword-model.xml"/>
+    <xi:include href="xml/dh-language.xml"/>
+    <xi:include href="xml/dh-link.xml"/>
+    <xi:include href="xml/dh-sidebar.xml"/>
+    <xi:include href="xml/dh-window.xml"/>
+
+  </chapter>
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+    <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+  <!-- enable this when you use gobject introspection annotations
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+  -->
+</book>
diff --git a/docs/reference/devhelp-overrides.txt b/docs/reference/devhelp-overrides.txt
new file mode 100644
index 0000000..e69de29
diff --git a/docs/reference/devhelp-sections.txt b/docs/reference/devhelp-sections.txt
new file mode 100644
index 0000000..48b8613
--- /dev/null
+++ b/docs/reference/devhelp-sections.txt
@@ -0,0 +1,257 @@
+<SECTION>
+<FILE>init</FILE>
+<TITLE>Initialization</TITLE>
+dh_init
+</SECTION>
+
+<SECTION>
+<FILE>dh-app</FILE>
+<TITLE>DhApp</TITLE>
+DhApp
+DhAppClass
+dh_app_new
+dh_app_peek_book_manager
+dh_app_peek_first_window
+dh_app_peek_assistant
+dh_app_new_window
+dh_app_quit
+dh_app_search
+dh_app_search_assistant
+dh_app_raise
+<SUBSECTION Standard>
+DH_APP
+DH_APP_CLASS
+DH_APP_GET_CLASS
+DH_IS_APP
+DH_IS_APP_CLASS
+DH_TYPE_APP
+<SUBSECTION Private>
+dh_app_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-assistant</FILE>
+<TITLE>DhAssistant</TITLE>
+DhAssistant
+DhAssistantClass
+dh_assistant_new
+dh_assistant_search
+<SUBSECTION Standard>
+DH_ASSISTANT
+DH_ASSISTANT_CLASS
+DH_ASSISTANT_GET_CLASS
+DH_IS_ASSISTANT
+DH_IS_ASSISTANT_CLASS
+DH_TYPE_ASSISTANT
+<SUBSECTION Private>
+dh_assistant_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-assistant-view</FILE>
+<TITLE>DhAssistantView</TITLE>
+DhAssistantView
+DhAssistantViewClass
+dh_assistant_view_new
+dh_assistant_view_search
+dh_assistant_view_set_book_manager
+dh_assistant_view_set_link
+<SUBSECTION Standard>
+DH_ASSISTANT_VIEW
+DH_ASSISTANT_VIEW_CLASS
+DH_ASSISTANT_VIEW_GET_CLASS
+DH_IS_ASSISTANT_VIEW
+DH_IS_ASSISTANT_VIEW_CLASS
+DH_TYPE_ASSISTANT_VIEW
+<SUBSECTION Private>
+dh_assistant_view_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-book</FILE>
+<TITLE>DhBook</TITLE>
+DhBook
+DhBookClass
+dh_book_new
+dh_book_get_keywords
+dh_book_get_completions
+dh_book_get_tree
+dh_book_get_name
+dh_book_get_title
+dh_book_get_language
+dh_book_get_path
+dh_book_get_enabled
+dh_book_set_enabled
+dh_book_cmp_by_path
+dh_book_cmp_by_path_str
+dh_book_cmp_by_name
+dh_book_cmp_by_name_str
+dh_book_cmp_by_title
+<SUBSECTION Standard>
+DH_BOOK
+DH_BOOK_CLASS
+DH_BOOK_GET_CLASS
+DH_IS_BOOK
+DH_IS_BOOK_CLASS
+DH_TYPE_BOOK
+<SUBSECTION Private>
+dh_book_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-book-manager</FILE>
+<TITLE>DhBookManager</TITLE>
+DhBookManager
+DhBookManagerClass
+dh_book_manager_new
+dh_book_manager_populate
+dh_book_manager_get_books
+dh_book_manager_get_languages
+dh_book_manager_get_group_by_language
+dh_book_manager_set_group_by_language
+<SUBSECTION Standard>
+DH_BOOK_MANAGER
+DH_BOOK_MANAGER_CLASS
+DH_BOOK_MANAGER_GET_CLASS
+DH_IS_BOOK_MANAGER
+DH_IS_BOOK_MANAGER_CLASS
+DH_TYPE_BOOK_MANAGER
+<SUBSECTION Private>
+dh_book_manager_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-book-tree</FILE>
+<TITLE>DhBookTree</TITLE>
+DhBookTree
+DhBookTreeClass
+dh_book_tree_new
+dh_book_tree_select_uri
+dh_book_tree_get_selected_book
+<SUBSECTION Standard>
+DH_BOOK_TREE
+DH_BOOK_TREE_CLASS
+DH_IS_BOOK_TREE
+DH_IS_BOOK_TREE_CLASS
+DH_TYPE_BOOK_TREE
+<SUBSECTION Private>
+dh_book_tree_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-error</FILE>
+<TITLE>DhError</TITLE>
+DhError
+dh_error_quark
+<SUBSECTION Standard>
+DH_ERROR
+DH_TYPE_ERROR
+<SUBSECTION Private>
+dh_error_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-keyword-model</FILE>
+<TITLE>DhKeywordModel</TITLE>
+DhKeywordModel
+DhKeywordModelClass
+dh_keyword_model_new
+dh_keyword_model_set_words
+dh_keyword_model_filter
+<SUBSECTION Standard>
+DH_IS_KEYWORD_MODEL
+DH_IS_KEYWORD_MODEL_CLASS
+DH_KEYWORD_MODEL
+DH_KEYWORD_MODEL_CLASS
+DH_KEYWORD_MODEL_GET_CLASS
+DH_TYPE_KEYWORD_MODEL
+<SUBSECTION Private>
+dh_keyword_model_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-language</FILE>
+<TITLE>DhLanguage</TITLE>
+DhLanguage
+dh_language_new
+dh_language_free
+dh_language_get_name
+dh_language_compare
+dh_language_compare_by_name
+dh_language_get_n_books_enabled
+dh_language_inc_n_books_enabled
+dh_language_dec_n_books_enabled
+</SECTION>
+
+<SECTION>
+<FILE>dh-link</FILE>
+<TITLE>DhLink</TITLE>
+DhLink
+dh_link_new
+dh_link_free
+dh_link_compare
+dh_link_ref
+dh_link_unref
+dh_link_get_name
+dh_link_get_book_name
+dh_link_get_page_name
+dh_link_get_file_name
+dh_link_get_book_id
+dh_link_get_uri
+dh_link_get_flags
+dh_link_set_flags
+dh_link_get_link_type
+dh_link_get_type_as_string
+DhLinkType
+DhLinkFlags
+<SUBSECTION Standard>
+DH_TYPE_LINK
+DH_TYPE_LINK_FLAGS
+DH_TYPE_LINK_TYPE
+<SUBSECTION Private>
+dh_link_get_type
+dh_link_flags_get_type
+dh_link_type_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-sidebar</FILE>
+<TITLE>DhSidebar</TITLE>
+DhSidebar
+DhSidebarClass
+dh_sidebar_new
+dh_sidebar_get_selected_book
+dh_sidebar_select_uri
+dh_sidebar_set_search_string
+dh_sidebar_set_search_focus
+<SUBSECTION Standard>
+DH_IS_SIDEBAR
+DH_IS_SIDEBAR_CLASS
+DH_SIDEBAR
+DH_SIDEBAR_CLASS
+DH_TYPE_SIDEBAR
+<SUBSECTION Private>
+dh_sidebar_get_type
+</SECTION>
+
+<SECTION>
+<FILE>dh-window</FILE>
+<TITLE>DhWindow</TITLE>
+DhWindow
+DhWindowClass
+dh_window_new
+dh_window_search
+DhOpenLinkFlags
+<SUBSECTION Standard>
+DH_IS_WINDOW
+DH_IS_WINDOW_CLASS
+DH_TYPE_WINDOW
+DH_WINDOW
+DH_WINDOW_CLASS
+DH_WINDOW_GET_CLASS
+DH_TYPE_OPEN_LINK_FLAGS
+<SUBSECTION Private>
+dh_window_get_type
+dh_open_link_flags_get_type
+</SECTION>
+
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-settings.h b/src/dh-settings.h
index dd3dd44..ef971e2 100644
--- a/src/dh-settings.h
+++ b/src/dh-settings.h
@@ -39,13 +39,18 @@ typedef struct _DhSettingsPrivate DhSettingsPrivate;
 
 struct _DhSettings{
         GObject parent;
-        /*<private>*/
+        /*< private >*/
         DhSettingsPrivate *priv;
 };
 
+/**
+ * DhSettingsClass:
+ * @parent: The parent class.
+ * @fonts_changed: Class handler for the #DhSettings::fonts-changed signal
+ */
 struct _DhSettingsClass{
         GObjectClass parent;
-        /* Signals */
+        /*< 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..49f2400 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,6 +51,11 @@ 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;
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]