Merge pull request #890 from kugel-/gtkdoc-hdr

Generated and ship a GtkDoc header suitable for GObject Introspection.

.gitignore

@@ -99,6 +99,7 @@ Makefile.in
 # /doc/
 #-----------------------------------------------------------------------
 /doc/Doxyfile
+/doc/Doxyfile-gi
 /doc/Doxyfile.stamp
 /doc/geany.1
 /doc/geany.html
@@ -110,6 +111,8 @@ Makefile.in
 /doc/*.tex
 /doc/*.toc
 /doc/reference
+/doc/geany-gtkdoc.h
+/doc/xml/
 
 #-----------------------------------------------------------------------
 # /tests/

.travis.yml

@@ -16,6 +16,7 @@ install:
   - sudo apt-get install -y python-docutils rst2pdf
   # try not to install doxygen-latex because we don't need it and it's huge
   - sudo apt-get install -y --no-install-recommends doxygen
+  - sudo apt-get install -y python-lxml
 before_script:
   - export CFLAGS="-g -O2 -Werror=pointer-arith -Werror=aggregate-return -Werror=implicit-function-declaration"
 script:

Makefile.am

@@ -5,7 +5,8 @@ SUBDIRS = tagmanager scintilla src plugins icons po doc data tests
 AUTOMAKE_OPTIONS =	1.7
 
 ACLOCAL_AMFLAGS = -I m4
-AM_DISTCHECK_CONFIGURE_FLAGS = --enable-api-docs --enable-html-docs --enable-pdf-docs
+AM_DISTCHECK_CONFIGURE_FLAGS = --enable-api-docs --enable-html-docs --enable-pdf-docs \
+                               --enable-gtkdoc-header
 
 WIN32_BUILD_FILES = \
 	geany_private.rc \
@@ -15,6 +16,7 @@ WIN32_BUILD_FILES = \
 
 EXTRA_DIST = \
 	autogen.sh \
+	scripts/gen-api-gtkdoc.py \
 	wscript \
 	waf \
 	geany.desktop.in \

configure.ac

@@ -123,6 +123,7 @@ AC_SUBST([pkgdatadir])
 # Documentation tools
 GEANY_CHECK_DOCUTILS
 GEANY_CHECK_DOXYGEN
+GEANY_CHECK_GTKDOC_HEADER
 
 # libgeany
 GEANY_LIB_INIT

doc/Doxyfile.in

@@ -247,7 +247,22 @@ ALIASES                = "signal=- @ref  " \
                          "endsignalproto=@endcode  " \
                          "signaldesc=" \
                          "signals=@b Signals:  " \
-                         "endsignals=  "
+                         "endsignals=  " \
+                         "gironly=@internal"
+
+# Apparently Doxygen doesn't seem to like \<type>only without a previous command, so create a no-op
+ALIASES               += "noop=\if FALSE \endif"
+ALIASES               += "transfer{1}=\noop \xmlonly <simplesect kind=\"geany:transfer\">\1</simplesect>\endxmlonly \htmlonly <em title=\"Ownership transfer to the caller: \1\">(transfer: \1)</em> \endhtmlonly"
+ALIASES               += "elementtype{1}=\noop \xmlonly <simplesect kind=\"geany:element-type\">\1</simplesect>\endxmlonly \htmlonly <em title=\"Type of the elements in the container: \1\">(element-type: \1)</em> \endhtmlonly"
+ALIASES               += "scope{1}=\noop \xmlonly <simplesect kind=\"geany:scope\">\1</simplesect>\endxmlonly \htmlonly <em>(scope: \1)</em> \endhtmlonly"
+ALIASES               += "girskip=\noop \xmlonly <simplesect kind=\"geany:skip\"></simplesect>\endxmlonly"
+ALIASES               += "nullable=\noop \xmlonly <simplesect kind=\"geany:nullable\"></simplesect>\endxmlonly"
+ALIASES               += "out=\noop \xmlonly <simplesect kind=\"geany:out\"></simplesect>\endxmlonly \htmlonly <em title=\"Output parameter\">(out)</em> \endhtmlonly"
+ALIASES               += "optional=\noop \xmlonly <simplesect kind=\"geany:optional\"></simplesect>\endxmlonly"
+ALIASES               += "cb=\noop \xmlonly <simplesect kind=\"geany:scope\">notified</simplesect>\endxmlonly"
+ALIASES               += "cbdata=\noop \xmlonly <simplesect kind=\"geany:closure\"></simplesect>\endxmlonly"
+ALIASES               += "cbfree=\noop \xmlonly <simplesect kind=\"geany:destroy\"></simplesect>\endxmlonly"
+
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding "class=itcl::class"
@@ -834,7 +849,7 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = @top_srcdir@/doc/geany-gtkdoc.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -2020,7 +2035,10 @@ INCLUDE_FILE_PATTERNS  =
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
 PREDEFINED             = "G_GNUC_PRINTF(x,y)=" \
+                         G_BEGIN_DECLS= \
+                         G_END_DECLS= \
                          HAVE_PLUGINS \
+                         GEANY_API_SYMBOL= \
                          GEANY_FUNCTIONS_H
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this

doc/Makefile.am

@@ -102,12 +102,49 @@ doxygen_sources = \
 Doxyfile.stamp: Doxyfile $(doxygen_sources)
 	$(AM_V_GEN)$(DOXYGEN) Doxyfile && echo "" > $@
 
-all-local: Doxyfile.stamp
+ALL_LOCAL_TARGETS = Doxyfile.stamp
+CLEAN_LOCAL_TARGETS = clean-api-docs-local
 
-clean-local: clean-api-docs-local
 clean-api-docs-local:
 	-rm -rf reference/ Doxyfile.stamp doxygen_*
 
+if ENABLE_GTKDOC_HEADER
+
+# set WARN_IF_UNDOCUMENTED because apparently doxygens warns for undocumented stuff
+# in headers (even though it's correctly documented in the corresponding .c file) only
+# for xml output
+Doxyfile-gi: Doxyfile
+	$(AM_V_GEN)$(SED) \
+		-e 's,gironly=@internal,gironly=,' \
+		-e 's,^\(GENERATE_HTML.*\)YES,\1NO,' \
+		-e 's,^\(GENERATE_XML.*\)NO,\1YES,' \
+		-e 's,^\(WARN_IF_UNDOCUMENTED.*\)YES,\1NO,' \
+		-e 's,^\(SORT_MEMBER_DOCS.*\)YES,\1NO,' \
+		-e 's,^\(SORT_BRIEF_DOCS.*\)YES,\1NO,' \
+		$< > $@ || { $(RM) $@ && exit 1; }
+
+# we depend on Doxyfile.stamp not have this run in parallel with it to avoid
+# concurrent Doxygen runs, which might overwrite each other's files
+Doxyfile-gi.stamp: Doxyfile-gi Doxyfile.stamp $(doxygen_sources)
+	$(AM_V_GEN)$(DOXYGEN) Doxyfile-gi && echo "" > $@
+
+geany-gtkdoc.h: Doxyfile-gi.stamp $(top_srcdir)/scripts/gen-api-gtkdoc.py
+	$(AM_V_GEN)$(top_srcdir)/scripts/gen-api-gtkdoc.py xml -d $(builddir) -o $@
+
+geany_gtkdocincludedir = $(includedir)/geany/gtkdoc
+nodist_geany_gtkdocinclude_HEADERS = geany-gtkdoc.h
+
+ALL_LOCAL_TARGETS += geany-gtkdoc.h
+CLEAN_LOCAL_TARGETS += clean-gtkdoc-header-local
+
+clean-gtkdoc-header-local:
+	-rm -rf xml/ Doxyfile-gi Doxyfile-gi.stamp geany-gtkdoc.h
+
+endif
+
+all-local: $(ALL_LOCAL_TARGETS)
+clean-local: $(CLEAN_LOCAL_TARGETS)
+
 endif
 
 uninstall-local:

doc/pluginsymbols.c

@@ -87,7 +87,9 @@ KeyBindingGroup *plugin_key_group;
  * @param dialog The plugin preferences dialog widget - this should only be used to
  * connect the @c "response" signal. If settings should be read from the dialog, the
  * response will be either @c GTK_RESPONSE_OK or @c GTK_RESPONSE_APPLY.
- * @return A container widget holding preference widgets.
+ *
+ * @return @transfer{floating} A container widget holding preference widgets.
+ *
  * @note Using @link stash.h Stash @endlink can make implementing preferences easier.
  * @see plugin_configure_single(). */
 GtkWidget *plugin_configure(GtkDialog *dialog);

m4/geany-gtkdoc-header.m4

@@ -0,0 +1,42 @@
+AC_DEFUN([_GEANY_CHECK_GTKDOC_HEADER_ERROR],
+[
+	AC_MSG_ERROR([GtkDoc header generation enabled but $1])
+])
+
+dnl GEANY_CHECK_GTKDOC_HEADER
+dnl checks for GtkDoc header generation requirements and define
+dnl ENABLE_GTKDOC_HEADER Automake conditional as appropriate
+AC_DEFUN([GEANY_CHECK_GTKDOC_HEADER],
+[
+	AC_REQUIRE([GEANY_CHECK_DOXYGEN])
+
+	AC_ARG_ENABLE([gtkdoc-header],
+			[AS_HELP_STRING([--enable-gtkdoc-header],
+					[generate the GtkDoc header suitable for GObject introspection [default=auto]])],
+			[geany_enable_gtkdoc_header="$enableval"],
+			[geany_enable_gtkdoc_header="auto"])
+
+	AS_IF([test "x$geany_enable_gtkdoc_header$geany_with_doxygen" = "xyesno"],
+	      [_GEANY_CHECK_GTKDOC_HEADER_ERROR([Doxygen support not available])],
+	      [test "x$geany_enable_gtkdoc_header" != "xno"],
+	[
+		dnl python
+		AM_PATH_PYTHON([2.7], [have_python=yes], [have_python=no])
+		dnl lxml module
+		AS_IF([test "x$have_python" = xyes],
+		      [have_python_and_lxml=yes
+		       AC_MSG_CHECKING([for python lxml package])
+		       AS_IF([$PYTHON -c 'import lxml' 2>&1 >/dev/null],
+		             [have_python_and_lxml=yes],
+		             [have_python_and_lxml=no])
+		       AC_MSG_RESULT([$have_python_and_lxml])],
+		      [have_python_and_lxml=no])
+		dnl final result
+		AS_IF([test "x$geany_enable_gtkdoc_header$have_python_and_lxml" = "xyesno"],
+		      [_GEANY_CHECK_GTKDOC_HEADER_ERROR([python or its lxml module not found])],
+		      [geany_enable_gtkdoc_header=yes])
+	])
+
+	AM_CONDITIONAL([ENABLE_GTKDOC_HEADER], [test "x$geany_enable_gtkdoc_header" = "xyes"])
+	GEANY_STATUS_ADD([Generate GtkDoc header], [$geany_enable_gtkdoc_header])
+])