dev-util/gtk-doc: add patches to fix glib api doc generation

Package-Manager: Portage-2.3.84, Repoman-2.3.20
Signed-off-by: Mart Raudsepp <leio@gentoo.org>

2 files changed, 284 insertions, 0 deletions

diff --git a/dev-util/gtk-doc/files/1.32-deprecation-parse-fixes.patch b/dev-util/gtk-doc/files/1.32-deprecation-parse-fixes.patch
new file mode 100644
index 000000000000..59f878cceac4
--- /dev/null
+++ b/dev-util/gtk-doc/files/1.32-deprecation-parse-fixes.patch
@@ -0,0 +1,180 @@
+From 2667d8cd95a2a29c35c1bb8f4629c22fd0aa98e9 Mon Sep 17 00:00:00 2001
+From: Xavier Claessens <xavier.claessens@collabora.com>
+Date: Thu, 2 Jan 2020 21:56:10 -0500
+Subject: [PATCH 1/3] Skip G_GNUC_(BEGIN|END)_IGNORE_DEPRECATIONS lines
+
+For some reason, glib has to put empty line before and after each of
+these lines otherwise the symbol following it is undeclared.
+---
+ gtkdoc/scan.py | 5 +++++
+ 1 file changed, 5 insertions(+)
+
+diff --git a/gtkdoc/scan.py b/gtkdoc/scan.py
+index d04d4d4..7de08ad 100644
+--- a/gtkdoc/scan.py
++++ b/gtkdoc/scan.py
+@@ -561,6 +561,11 @@ def ScanHeaderContent(input_lines, decl_list, get_types, options):
+                     logging.info('Found start of comment: %s', line.strip())
+                 continue
+ 
++            # Skip begin/end deprecation macros.
++            m = re.search(r'^\s*G_GNUC_(BEGIN|END)_IGNORE_DEPRECATIONS', line)
++            if m:
++                continue
++
+             logging.info('no decl: %s', line.strip())
+ 
+             cm = [m.match(line) for m in CLINE_MATCHER]
+-- 
+2.20.1
+
+
+From 9e58548688c9768cf41c59ccef531d438ffb2504 Mon Sep 17 00:00:00 2001
+From: Xavier Claessens <xavier.claessens@collabora.com>
+Date: Fri, 3 Jan 2020 06:47:47 -0500
+Subject: [PATCH 2/3] typedef can be followed by decorator
+
+---
+ gtkdoc/scan.py | 30 +++++++++++++++++-------------
+ 1 file changed, 17 insertions(+), 13 deletions(-)
+
+diff --git a/gtkdoc/scan.py b/gtkdoc/scan.py
+index 7de08ad..5a5da92 100644
+--- a/gtkdoc/scan.py
++++ b/gtkdoc/scan.py
+@@ -96,19 +96,8 @@ CLINE_MATCHER = [
+         (struct|union)\s*
+         \w*\s*{""", re.VERBOSE),
+     # 12-14: OTHER TYPEDEFS
+-    re.compile(
+-        r"""^\s*typedef\s+
+-        (?:struct|union)\s+\w+[\s\*]+
+-        (\w+)                                # 1: name
+-        \s*;""", re.VERBOSE),
+-    re.compile(
+-        r"""^\s*
+-        (?:G_GNUC_EXTENSION\s+)?
+-        typedef\s+
+-        (.+[\s\*])                           # 1: e.g. 'unsigned int'
+-        (\w+)                                # 2: name
+-        (?:\s*\[[^\]]+\])*
+-        \s*;""", re.VERBOSE),
++    None,  # in InitScanner()
++    None,  # in InitScanner()
+     re.compile(r'^\s*typedef\s+'),
+     # 15: VARIABLES (extern'ed variables)
+     None,  # in InitScanner()
+@@ -267,6 +256,21 @@ def InitScanner(options):
+         %s                                   # 3: optional decorator
+         \s*;""" % optional_decorators_regex, re.VERBOSE)
+     # OTHER TYPEDEFS
++    CLINE_MATCHER[12] = re.compile(
++        r"""^\s*typedef\s+
++        (?:struct|union)\s+\w+[\s\*]+
++        (\w+)                                # 1: name
++        %s                                   # 2: optional decorator
++        \s*;""" % optional_decorators_regex, re.VERBOSE)
++    CLINE_MATCHER[13] = re.compile(
++        r"""^\s*
++        (?:G_GNUC_EXTENSION\s+)?
++        typedef\s+
++        (.+?[\s\*])                          # 1: e.g. 'unsigned int'
++        (\w+)                                # 2: name
++        (?:\s*\[[^\]]+\])*
++        %s                                   # 3: optional decorator
++        \s*;""" % optional_decorators_regex, re.VERBOSE)
+     CLINE_MATCHER[15] = re.compile(
+         r"""^\s*
+         (?:extern|[A-Za-z_]+VAR%s)\s+
+-- 
+2.20.1
+
+
+From 5bfe23f0257e1b4c6c9a4e3a2dbb180455f753f2 Mon Sep 17 00:00:00 2001
+From: Jason Crain <jason@inspiresomeone.us>
+Date: Mon, 6 Jan 2020 19:05:42 -0700
+Subject: [PATCH 3/3] scan: support deprecated struct members
+
+gcc allows deprecating members of structs. For example:
+
+struct data {
+  int x G_GNUC_DEPRECATED_FOR(replacement);
+};
+
+However, this currently causes the entire struct to be marked as
+deprecated and confuses mkdb because it doesn't understand the
+G_GNUC_DEPRECATED_FOR symbol.
+
+Fix this by having the whole struct only be marked as deprecated if the
+'_DEPRECATED' is after the closing bracket of the struct, similar to how
+it already does for enums, and having scan automatically remove all
+G_GNUC_* decorators from struct members, similar to how it already does
+for functions.
+---
+ gtkdoc/scan.py | 12 ++++++++++--
+ tests/scan.py  | 17 +++++++++++++++++
+ 2 files changed, 27 insertions(+), 2 deletions(-)
+
+diff --git a/gtkdoc/scan.py b/gtkdoc/scan.py
+index 5a5da92..6c6534a 100644
+--- a/gtkdoc/scan.py
++++ b/gtkdoc/scan.py
+@@ -538,7 +538,7 @@ def ScanHeaderContent(input_lines, decl_list, get_types, options):
+         # section (#endif /* XXX_DEPRECATED */
+         if deprecated_conditional_nest == 0 and '_DEPRECATED' in line:
+             m = re.search(r'^\s*#\s*(if*|define|endif)', line)
+-            if not (m or in_declaration == 'enum'):
++            if not (m or in_declaration == 'enum' or in_declaration == 'struct'):
+                 logging.info('Found deprecation annotation (decl: "%s"): "%s"',
+                              in_declaration, line.strip())
+                 deprecated_conditional_nest += 0.1
+@@ -953,9 +953,17 @@ def ScanHeaderContent(input_lines, decl_list, get_types, options):
+                     title = '<TITLE>%s</TITLE>' % objectname
+ 
+                 logging.info('Store struct: "%s"', symbol)
++                # Structs could contain deprecated members and that doesn't
++                # mean the whole struct is deprecated, so they are ignored when
++                # setting deprecated_conditional_nest above. Here we can check
++                # if the _DEPRECATED is between '}' and ';' which would mean
++                # the struct as a whole is deprecated.
++                if re.search(r'\n\s*\}.*_DEPRECATED.*;\s*$', decl):
++                    deprecated = '<DEPRECATED/>\n'
+                 if AddSymbolToList(slist, symbol):
+                     structsym = in_declaration.upper()
+-                    stripped_decl = re.sub('(%s)' % optional_decorators_regex, '', decl)
++                    regex = r'(?:\s+(?:G_GNUC_\w+(?:\(\w*\))?%s))' % ignore_decorators
++                    stripped_decl = re.sub(regex, '', decl)
+                     decl_list.append('<%s>\n<NAME>%s</NAME>\n%s%s</%s>\n' %
+                                      (structsym, symbol, deprecated, stripped_decl, structsym))
+                     if symbol in forward_decls:
+diff --git a/tests/scan.py b/tests/scan.py
+index ad63541..6d608b6 100755
+--- a/tests/scan.py
++++ b/tests/scan.py
+@@ -552,6 +552,23 @@ class ScanHeaderContentStructs(ScanHeaderContentTestCase):
+         slist, doc_comments = self.scanHeaderContent([header])
+         self.assertDecl('data', expected, slist)
+ 
++    def test_HandleDeprecatedMemberDecorator(self):
++        """Struct with deprecated members."""
++        header = textwrap.dedent("""\
++            struct data {
++              int x1 G_GNUC_DEPRECATED;
++              int x2 G_GNUC_DEPRECATED_FOR(replacement);
++            };""")
++        expected = textwrap.dedent("""\
++            struct data {
++              int x1;
++              int x2;
++            };""")
++        scan.InitScanner(self.options)
++        slist, doc_comments = self.scanHeaderContent(
++                header.splitlines(keepends=True))
++        self.assertDecl('data', expected, slist)
++
+ 
+ class ScanHeaderContentUnions(ScanHeaderContentTestCase):
+     """Test parsing of union declarations."""
+-- 
+2.20.1
+
diff --git a/dev-util/gtk-doc/gtk-doc-1.32-r2.ebuild b/dev-util/gtk-doc/gtk-doc-1.32-r2.ebuild
new file mode 100644
index 000000000000..ce7456739f6d
--- /dev/null
+++ b/dev-util/gtk-doc/gtk-doc-1.32-r2.ebuild
@@ -0,0 +1,104 @@
+# Copyright 1999-2020 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+EAPI=6
+PYTHON_COMPAT=( python3_{6,7} )
+
+inherit eutils elisp-common gnome2 python-single-r1 readme.gentoo-r1
+
+DESCRIPTION="GTK+ Documentation Generator"
+HOMEPAGE="https://www.gtk.org/gtk-doc/"
+
+LICENSE="GPL-2 FDL-1.1"
+SLOT="0"
+KEYWORDS="~alpha ~amd64 ~arm ~arm64 ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sparc ~x86 ~amd64-linux ~x86-linux ~ppc-macos ~x86-macos ~sparc-solaris ~x64-solaris"
+
+IUSE="debug doc emacs"
+REQUIRED_USE="${PYTHON_REQUIRED_USE}"
+
+RDEPEND="
+	${PYTHON_DEPS}
+	>=dev-libs/glib-2.6:2
+	dev-libs/libxslt
+	>=dev-libs/libxml2-2.3.6:2
+	~app-text/docbook-xml-dtd-4.3
+	app-text/docbook-xsl-stylesheets
+	~app-text/docbook-sgml-dtd-3.0
+	>=app-text/docbook-dsssl-stylesheets-1.40
+	emacs? ( >=app-editors/emacs-23.1:* )
+	$(python_gen_cond_dep '
+		dev-python/pygments[${PYTHON_MULTI_USEDEP}]
+	')
+"
+DEPEND="${RDEPEND}
+	~dev-util/gtk-doc-am-${PV}
+	dev-util/itstool
+	virtual/pkgconfig
+"
+
+# tests require unpackaged python module "anytree", and require java(fop) or tex(dblatex)
+RESTRICT="test"
+
+pkg_setup() {
+	DOC_CONTENTS="gtk-doc does no longer define global key bindings for Emacs.
+		You may set your own key bindings for \"gtk-doc-insert\" and
+		\"gtk-doc-insert-section\" in your ~/.emacs file."
+	SITEFILE=61${PN}-gentoo.el
+	python-single-r1_pkg_setup
+}
+
+src_prepare() {
+	# Remove global Emacs keybindings, bug #184588
+	eapply "${FILESDIR}"/${PN}-1.8-emacs-keybindings.patch
+	# Fix dev-libs/glib[gtk-doc] doc generation tests by fixing stuff surrounding deprecations
+	# https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1488
+	eapply "${FILESDIR}"/${PV}-deprecation-parse-fixes.patch
+
+	gnome2_src_prepare
+}
+
+src_configure() {
+	gnome2_src_configure \
+		--with-xml-catalog="${EPREFIX}"/etc/xml/catalog \
+		$(use_enable debug)
+}
+
+src_compile() {
+	gnome2_src_compile
+	use emacs && elisp-compile tools/gtk-doc.el
+}
+
+src_install() {
+	gnome2_src_install
+
+	python_fix_shebang "${ED}"/usr/bin/gtkdoc-depscan
+
+	# Don't install this file, it's in gtk-doc-am now
+	rm "${ED}"/usr/share/aclocal/gtk-doc.m4 || die "failed to remove gtk-doc.m4"
+
+	if use doc; then
+		docinto doc
+		dodoc doc/*
+		docinto examples
+		dodoc examples/*
+	fi
+
+	if use emacs; then
+		elisp-install ${PN} tools/gtk-doc.el*
+		elisp-site-file-install "${FILESDIR}/${SITEFILE}"
+		readme.gentoo_create_doc
+	fi
+}
+
+pkg_postinst() {
+	gnome2_pkg_postinst
+	if use emacs; then
+		elisp-site-regen
+		readme.gentoo_print_elog
+	fi
+}
+
+pkg_postrm() {
+	gnome2_pkg_postrm
+	use emacs && elisp-site-regen
+}