[gimp/nielsdg/gi-docgen: 12/12] docs: Migrate from gtk-doc to docgen
- From: Niels De Graef <nielsdg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gimp/nielsdg/gi-docgen: 12/12] docs: Migrate from gtk-doc to docgen
- Date: Wed, 8 Dec 2021 08:47:17 +0000 (UTC)
commit f40e2301930dbe1ce1ce436f0fc69f3f00f266db
Author: Niels De Graef <nielsdegraef gmail com>
Date: Sun Nov 28 19:36:07 2021 +0100
docs: Migrate from gtk-doc to docgen
gtk-doc has been slowly dying for the past few years; with gi-docgen we
have a nice successor.
This also makes sure the C documentation also uses the GIR file, which
in turn means faster build times (since all the C code doesn't have to
be parsed and recompiled again), and has a clear dependency graph.
See the [gi-docgen tutorial] for more info on how the system works.
[gi-docgen tutorial]: https://gnome.pages.gitlab.gnome.org/gi-docgen/tutorial.html
.gitlab-ci.yml | 9 +-
CODING_STYLE.md | 4 +-
HACKING | 3 -
Makefile.am | 3 +-
autogen.sh | 42 -
build/flatpak/org.gimp.GIMP-nightly.json | 3 +-
configure.ac | 38 +-
data/images/meson.build | 1 +
devel-docs/Makefile.am | 33 +-
devel-docs/README.gtkdoc | 128 -
devel-docs/app/.gitignore | 20 -
devel-docs/app/Makefile.am | 128 -
devel-docs/app/app-docs.sgml | 1404 --
devel-docs/app/app-overrides.txt | 0
devel-docs/app/app-sections.txt | 13957 -------------------
devel-docs/app/app.types | 442 -
devel-docs/app/meson.build | 98 -
devel-docs/libgimp/Makefile.am | 85 -
devel-docs/libgimp/libgimp3-docs.sgml | 182 -
devel-docs/libgimp/libgimp3-include.c | 15 -
devel-docs/libgimp/libgimp3-overrides.txt | 0
devel-docs/libgimp/libgimp3-sections.txt | 1810 ---
devel-docs/libgimp/libgimp3.types | 39 -
devel-docs/libgimp/meson.build | 54 -
devel-docs/libgimpbase/.gitignore | 21 -
devel-docs/libgimpbase/Makefile.am | 65 -
devel-docs/libgimpbase/libgimpbase3-docs.sgml | 69 -
devel-docs/libgimpbase/libgimpbase3-overrides.txt | 0
devel-docs/libgimpbase/libgimpbase3-sections.txt | 552 -
devel-docs/libgimpbase/libgimpbase3.types | 17 -
devel-docs/libgimpbase/meson.build | 39 -
devel-docs/libgimpcolor/.gitignore | 20 -
devel-docs/libgimpcolor/Makefile.am | 58 -
devel-docs/libgimpcolor/libgimpcolor3-docs.sgml | 67 -
.../libgimpcolor/libgimpcolor3-overrides.txt | 0
devel-docs/libgimpcolor/libgimpcolor3-sections.txt | 212 -
devel-docs/libgimpcolor/libgimpcolor3.types | 3 -
devel-docs/libgimpcolor/meson.build | 21 -
devel-docs/libgimpconfig/.gitignore | 20 -
devel-docs/libgimpconfig/Makefile.am | 64 -
devel-docs/libgimpconfig/libgimpconfig3-docs.sgml | 69 -
.../libgimpconfig/libgimpconfig3-overrides.txt | 0
.../libgimpconfig/libgimpconfig3-sections.txt | 206 -
devel-docs/libgimpconfig/libgimpconfig3.types | 7 -
devel-docs/libgimpconfig/meson.build | 30 -
devel-docs/libgimpmath/.gitignore | 19 -
devel-docs/libgimpmath/Makefile.am | 50 -
devel-docs/libgimpmath/libgimpmath3-docs.sgml | 47 -
devel-docs/libgimpmath/libgimpmath3-overrides.txt | 0
devel-docs/libgimpmath/libgimpmath3-sections.txt | 119 -
devel-docs/libgimpmath/libgimpmath3.types | 0
devel-docs/libgimpmath/meson.build | 14 -
devel-docs/libgimpmodule/.gitignore | 20 -
devel-docs/libgimpmodule/Makefile.am | 59 -
devel-docs/libgimpmodule/libgimpmodule3-docs.sgml | 38 -
.../libgimpmodule/libgimpmodule3-overrides.txt | 0
.../libgimpmodule/libgimpmodule3-sections.txt | 57 -
devel-docs/libgimpmodule/libgimpmodule3.types | 6 -
devel-docs/libgimpmodule/meson.build | 23 -
devel-docs/libgimpthumb/.gitignore | 20 -
devel-docs/libgimpthumb/Makefile.am | 59 -
devel-docs/libgimpthumb/libgimpthumb3-docs.sgml | 40 -
.../libgimpthumb/libgimpthumb3-overrides.txt | 0
devel-docs/libgimpthumb/libgimpthumb3-sections.txt | 67 -
devel-docs/libgimpthumb/libgimpthumb3.types | 4 -
devel-docs/libgimpthumb/meson.build | 28 -
devel-docs/libgimpwidgets/.gitignore | 19 -
devel-docs/libgimpwidgets/Makefile.am | 89 -
.../libgimpwidgets/libgimpwidgets3-docs.sgml | 151 -
.../libgimpwidgets/libgimpwidgets3-overrides.txt | 0
.../libgimpwidgets/libgimpwidgets3-sections.txt | 1557 ---
devel-docs/libgimpwidgets/libgimpwidgets3.types | 52 -
devel-docs/libgimpwidgets/meson.build | 81 -
devel-docs/libgimpwidgets/tmpl/.gitignore | 58 -
devel-docs/libgimpwidgets/tmpl/gimpstock.sgml | 1553 ---
devel-docs/libgimpwidgets/visual-index.xml | 100 -
devel-docs/meson.build | 16 +-
devel-docs/{libgimp => reference}/.gitignore | 0
devel-docs/reference/Makefile.am | 7 +
devel-docs/reference/gimp-ui/Makefile.am | 26 +
devel-docs/reference/gimp-ui/gimp-ui-3.0.toml.in | 108 +
.../gimp-ui/images/browser.png} | Bin
.../gimp-ui/images/busy-box.png} | Bin
.../gimp-ui/images/button.png} | Bin
.../gimp-ui/images/chain-button.png} | Bin
.../gimp-ui/images/color-area.png} | Bin
.../gimp-ui/images/color-button.png} | Bin
.../gimp-ui/images/color-hex-entry.png} | Bin
.../gimp-ui/images/color-notebook.png} | Bin
.../gimp-ui/images/color-profile-combo-box.png} | Bin
.../gimp-ui/images/color-profile-view.png} | Bin
.../gimp-ui/images/color-scale.png} | Bin
.../gimp-ui/images/color-scales.png} | Bin
.../gimp-ui/images/color-select.png} | Bin
.../gimp-ui/images/color-selection.png} | Bin
.../gimp-ui/images/dialog.png} | Bin
.../gimp-ui/images/enum-combo-box.png} | Bin
.../gimp-ui/images/enum-label.png} | Bin
.../gimp-ui/images/file-entry.png} | Bin
.../gimp-ui/images/frame.png} | Bin
.../gimp-ui/images/hint-box.png} | Bin
.../gimp-ui/images/int-combo-box.png} | Bin
.../gimp-ui/images/memsize-entry.png} | Bin
.../gimp-ui/images/number-pair-entry.png} | Bin
.../gimp-ui/images/offset-area.png} | Bin
.../gimp-ui/images/page-selector.png} | Bin
.../gimp-ui/images/path-editor.png} | Bin
.../gimp-ui/images/pick-button.png} | Bin
.../gimp-ui/images/preview-area.png} | Bin
.../gimp-ui/images/ruler.png} | Bin
.../gimp-ui/images/string-combo-box.png} | Bin
.../gimp-ui/images/unit-combo-box.png} | Bin
devel-docs/reference/gimp-ui/meson.build | 37 +
devel-docs/reference/gimp-ui/widget-gallery.md | 36 +
devel-docs/reference/gimp/Makefile.am | 24 +
devel-docs/reference/gimp/gimp-3.0.toml.in | 74 +
devel-docs/reference/gimp/meson.build | 35 +
devel-docs/reference/meson.build | 4 +
devel-docs/tools/.gitignore | 6 -
devel-docs/tools/Makefile.am | 55 -
devel-docs/tools/README.shooter | 13 -
devel-docs/tools/meson.build | 28 -
devel-docs/tools/shadow.c | 149 -
devel-docs/tools/shadow.h | 8 -
devel-docs/tools/shooter.c | 178 -
devel-docs/tools/units.c | 102 -
devel-docs/tools/units.h | 8 -
devel-docs/tools/widgets.c | 873 --
devel-docs/tools/widgets.h | 25 -
libgimp/gimpplugin.c | 156 +-
libgimp/gimpplugin.h | 81 +-
meson_options.txt | 3 +-
132 files changed, 497 insertions(+), 25923 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index dd3bebf977..1f578d72eb 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -70,7 +70,8 @@ build-image:
- echo "FROM debian:testing" > Dockerfile
- echo "RUN apt-get update" >> Dockerfile
- echo "RUN apt-get install -y --no-install-recommends \\" >> Dockerfile
- - echo "at-spi2-core build-essential desktop-file-utils ffmpeg ghostscript git glib-networking
gobject-introspection graphviz graphviz-dev gtk-doc-tools hicolor-icon-theme intltool iso-codes
libappstream-glib-dev libbz2-dev libdbus-glib-1-dev libexif-dev libgexiv2-dev libgirepository1.0-dev
libgtk-3-bin libgtk-3-dev libgudev-1.0-dev libjson-glib-dev liblcms2-dev liblzma-dev libmng-dev
libmypaint-dev libopenexr-dev libpoppler-glib-dev libraw-dev libraw20 librsvg2-dev libspiro-dev
libsuitesparse-dev libtiff-dev libtiff5-dev libtool libumfpack5 libwebp-dev libwmf-dev libxmu-dev libxpm-dev
luajit meson mypaint-brushes poppler-data python3 valac xauth xvfb" >> Dockerfile
+ - echo "at-spi2-core build-essential desktop-file-utils ffmpeg ghostscript git glib-networking
gobject-introspection graphviz graphviz-dev hicolor-icon-theme intltool iso-codes libappstream-glib-dev
libbz2-dev libdbus-glib-1-dev libexif-dev libgexiv2-dev libgirepository1.0-dev libgtk-3-bin libgtk-3-dev
libgudev-1.0-dev libjson-glib-dev liblcms2-dev liblzma-dev libmng-dev libmypaint-dev libopenexr-dev
libpoppler-glib-dev libraw-dev libraw20 librsvg2-dev libspiro-dev libsuitesparse-dev libtiff-dev libtiff5-dev
libtool libumfpack5 libwebp-dev libwmf-dev libxmu-dev libxpm-dev luajit meson mypaint-brushes poppler-data
python3 python3-pip valac xauth xsltproc xvfb" >> Dockerfile
+ - echo "RUN pip3 install gi-docgen jinja2 Markdown markupsafe pygments toml typogrify" >> Dockerfile
- /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination
$CI_REGISTRY_IMAGE:build-debian-latest --cache=true --cache-ttl=120h
@@ -210,7 +211,7 @@ gimp-distcheck-debian:
- ../autogen.sh
--prefix="${INSTALL_PREFIX}"
--enable-debug
- --enable-gtk-doc
+ --enable-gi-docgen
--enable-windows-installer
- make -j "$(nproc)"
- make -j "$(nproc)" check
@@ -487,7 +488,7 @@ gimp-win64:
- export PATH="`pwd`/.local/bin:$PATH"
- mkdir _build && cd _build
- echo 'crossroad meson ..
- -Dgtk-doc=false && ninja && ninja install &&
+ -Dgi-docgen=false && ninja && ninja install &&
cp -fr $CROSSROAD_PREFIX/ ../gimp-prefix/
' |
crossroad w64 gimp --run="-"
@@ -552,7 +553,7 @@ gimp-win32:
- export PATH="`pwd`/.local/bin:$PATH"
- mkdir _build && cd _build
- echo 'crossroad meson ..
- -Dwmf=disabled -Dmng=disabled -Dgtk-doc=false && ninja && ninja install &&
+ -Dwmf=disabled -Dmng=disabled -Dgi_docgen=false && ninja && ninja install &&
cp -fr $CROSSROAD_PREFIX/ ../gimp-prefix/
' |
crossroad w32 gimp --run="-"
diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index ec265be00f..7094e9cb86 100644
--- a/CODING_STYLE.md
+++ b/CODING_STYLE.md
@@ -645,8 +645,8 @@ which often revamp their design, breaking URLs, etc.).
#### Public API Documentation
All public APIs (i.e. any function exported in a header inside
-`libgimp*/` folders) **MUST** have proper gtk-doc comments. For
-functions, these should be placed in the source file directly above.
+`libgimp*/` folders) **MUST** have proper GObject-introspection (GIR) comments.
+For functions, these should be placed in the source file directly above.
These annotations are also relevant for [GObject
Introspection](https://gi.readthedocs.io/en/latest/annotations/giannotations.html)
diff --git a/HACKING b/HACKING
index 004cd2ac61..fb17479186 100644
--- a/HACKING
+++ b/HACKING
@@ -20,9 +20,6 @@ Beta software can be found at alpha.gnu.org.
* pkg-config 0.16.0 (or preferably a newer version)
- https://www.freedesktop.org/software/pkgconfig/
- * gtkdocize
- - https://ftp.gnome.org/pub/GNOME/sources/gtk-doc/
-
* xsltproc
- ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.1/
diff --git a/Makefile.am b/Makefile.am
index 3d22f29089..d50c57fe9a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -87,10 +87,9 @@ EXTRA_DIST = \
config.h.win32 \
gimp-zip.in \
git-version.h \
- gtk-doc.make
-AM_DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --with-python=force --with-javascript=force --with-lua=force
+AM_DISTCHECK_CONFIGURE_FLAGS = --enable-gi-docgen --with-python=force --with-javascript=force
--with-lua=force
check-defs:
diff --git a/autogen.sh b/autogen.sh
index eb66aefb59..a7d21d1c9f 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -110,35 +110,6 @@ if test x$LIBTOOLIZE != x; then
check_version $VER $LIBTOOL_REQUIRED_VERSION
fi
-# check if gtk-doc is explicitly disabled
-for ag_option in $AUTOGEN_CONFIGURE_ARGS $@
-do
- case $ag_option in
- -disable-gtk-doc | --disable-gtk-doc)
- enable_gtk_doc=no
- ;;
- esac
-done
-
-if test x$enable_gtk_doc = xno; then
- echo "skipping test for gtkdocize"
-else
- printf "checking for gtkdocize ... "
- if (gtkdocize --version) < /dev/null > /dev/null 2>&1; then
- echo "yes"
- else
- echo
- echo " You must have gtk-doc installed to compile $PROJECT."
- echo " Install the appropriate package for your distribution,"
- echo " or get the source tarball at"
- echo " https://ftp.gnome.org/pub/GNOME/sources/gtk-doc/";
- echo " You can also use the option --disable-gtk-doc to skip"
- echo " this test but then you will not be able to generate a"
- echo " configure script that can build the API documentation."
- DIE=1
- fi
-fi
-
printf "checking for autoconf >= $AUTOCONF_REQUIRED_VERSION ... "
if ($AUTOCONF --version) < /dev/null > /dev/null 2>&1; then
VER=`$AUTOCONF --version | head -n 1 \
@@ -279,19 +250,6 @@ fi
$LIBTOOLIZE --force || exit $?
-if test x$enable_gtk_doc = xno; then
- if test -f gtk-doc.make; then :; else
- echo "EXTRA_DIST = missing-gtk-doc" > gtk-doc.make
- echo "CLEANFILES = " >> gtk-doc.make
- fi
- echo "WARNING: You have disabled gtk-doc."
- echo " As a result, you will not be able to generate the API"
- echo " documentation and 'make dist' will not work."
- echo
-else
- gtkdocize || exit $?
-fi
-
# optionally feature autoheader
($AUTOHEADER --version) < /dev/null > /dev/null 2>&1 && $AUTOHEADER || exit 1
diff --git a/build/flatpak/org.gimp.GIMP-nightly.json b/build/flatpak/org.gimp.GIMP-nightly.json
index 5025134aaa..ad290b52d8 100644
--- a/build/flatpak/org.gimp.GIMP-nightly.json
+++ b/build/flatpak/org.gimp.GIMP-nightly.json
@@ -36,7 +36,6 @@
"/share/aclocal",
"/man",
"/share/man",
- "/share/gtk-doc",
"/share/vala",
"*.la",
"*.a"
@@ -802,7 +801,7 @@
{
"name": "gimp",
"config-opts": [
- "-Dgtk-doc=false",
+ "-Dgi-docgen=false",
"-Dicc-directory=/run/host/usr/share/color/icc/",
"-Dbuild-id=org.gimp.GIMP.flatpak.nightly",
"-Dcheck-update=no"
diff --git a/configure.ac b/configure.ac
index b05ed166cd..6396dc7c2e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -2738,22 +2738,20 @@ if test "x$platform_osx" = "xno" &&
AC_MSG_RESULT([$with_icc_directory])
fi
-######################################
-# Checks for gtk-doc and docbook-tools
-######################################
+########################################
+# Check for gi-docgen
+########################################
-# Check for GTK_DOC_CHECK availability. The GTK_DOC_CHECK invocation
-# must be on its own line, gtkdocize relies on it
-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.0])
-])
+AC_ARG_ENABLE(gi-docgen, [ --enable-gi-docgen build gi-docgen documentation (default=yes)], ,
enable_gi_docgen=yes)
-# NOTE: We need to use a separate automake conditional for this
-# to make this work with the tarballs.
-AM_CONDITIONAL(ENABLE_GTK_DOC, test "x$enable_gtk_doc" = xyes)
+if test "x$enable_gi_docgen" = xyes; then
+ AC_PATH_PROG(GI_DOCGEN, gi-docgen, no)
+ if test "x$GI_DOCGEN" = xno; then
+ add_deps_error([gi-docgen], [Could not find gi-docgen in your PATH.])
+ fi
+fi
-AC_ARG_ENABLE(gtk-doc-app, [ --enable-gtk-doc-app build developer documentation for app (default=no)], ,
enable_gtk_doc_app=no)
-AM_CONDITIONAL(ENABLE_GTK_DOC_APP, test "x$enable_gtk_doc_app" = xyes)
+AM_CONDITIONAL(ENABLE_GI_DOCGEN, test "x$enable_gi_docgen" = xyes)
########################################
# Checks for gir-doc-tool and yelp-build
@@ -3099,19 +3097,11 @@ plug-ins/twain/Makefile
plug-ins/common/Makefile
modules/Makefile
devel-docs/Makefile
-devel-docs/version
-devel-docs/app/Makefile
devel-docs/g-ir-docs/Makefile
-devel-docs/libgimp/Makefile
-devel-docs/libgimpbase/Makefile
-devel-docs/libgimpconfig/Makefile
-devel-docs/libgimpcolor/Makefile
-devel-docs/libgimpmath/Makefile
-devel-docs/libgimpmodule/Makefile
-devel-docs/libgimpthumb/Makefile
-devel-docs/libgimpwidgets/Makefile
+devel-docs/reference/Makefile
+devel-docs/reference/gimp-ui/Makefile
+devel-docs/reference/gimp/Makefile
devel-docs/performance-logs/Makefile
-devel-docs/tools/Makefile
docs/Makefile
menus/Makefile
cursors/Makefile
diff --git a/data/images/meson.build b/data/images/meson.build
index 7ecce25387..a570661cf8 100644
--- a/data/images/meson.build
+++ b/data/images/meson.build
@@ -1,3 +1,4 @@
+gimp_logo_dir = meson.current_source_dir()
images = [
'gimp-splash.png',
diff --git a/devel-docs/Makefile.am b/devel-docs/Makefile.am
index 8062d27456..bd6d32501e 100644
--- a/devel-docs/Makefile.am
+++ b/devel-docs/Makefile.am
@@ -1,27 +1,13 @@
## Process this file with automake to produce Makefile.in
-if ENABLE_GTK_DOC_APP
-app = app
-endif
-
SUBDIRS = \
g-ir-docs \
- tools \
- libgimpbase \
- libgimpcolor \
- libgimpconfig \
- libgimpmath \
- libgimpmodule \
- libgimpthumb \
- libgimpwidgets \
- libgimp \
- $(app) \
+ reference \
\
performance-logs
EXTRA_DIST = \
README \
- README.gtkdoc \
contexts.txt \
debug-plug-ins.txt \
exif-handling.txt \
@@ -43,20 +29,3 @@ EXTRA_DIST = \
vbr.txt \
xcf.txt \
version.in
-
-
-# require gtk-doc when making dist
-#
-if ENABLE_GTK_DOC
-dist-check-gtk-doc:
-if ENABLE_GTK_DOC_APP
- @echo "*** gtk-doc-app must be disabled in order to make dist"
- @false
-endif
-else
-dist-check-gtk-doc:
- @echo "*** gtk-doc must be enabled in order to make dist"
- @false
-endif
-
-dist-hook: dist-check-gtk-doc
diff --git a/devel-docs/meson.build b/devel-docs/meson.build
index 48919e76c6..4f65f92edb 100644
--- a/devel-docs/meson.build
+++ b/devel-docs/meson.build
@@ -17,20 +17,8 @@ mkdb_args_common = [
]
-if get_option('gtk-doc')
- if get_option('gtk-doc-app')
- subdir('app')
- endif
-
- subdir('libgimp')
- subdir('libgimpbase')
- subdir('libgimpcolor')
- subdir('libgimpconfig')
- subdir('libgimpmath')
- subdir('libgimpmodule')
- subdir('libgimpthumb')
- subdir('libgimpwidgets')
- subdir('tools')
+if get_option('gi-docgen')
+ subdir('reference')
endif
if get_option('g-ir-doc')
diff --git a/devel-docs/libgimp/.gitignore b/devel-docs/reference/.gitignore
similarity index 100%
rename from devel-docs/libgimp/.gitignore
rename to devel-docs/reference/.gitignore
diff --git a/devel-docs/reference/Makefile.am b/devel-docs/reference/Makefile.am
new file mode 100644
index 0000000000..15a26c3e7a
--- /dev/null
+++ b/devel-docs/reference/Makefile.am
@@ -0,0 +1,7 @@
+## Process this file with automake to produce Makefile.in
+
+if ENABLE_GI_DOCGEN
+
+SUBDIRS = gimp gimp-ui
+
+endif
diff --git a/devel-docs/reference/gimp-ui/Makefile.am b/devel-docs/reference/gimp-ui/Makefile.am
new file mode 100644
index 0000000000..fe3a058bcc
--- /dev/null
+++ b/devel-docs/reference/gimp-ui/Makefile.am
@@ -0,0 +1,26 @@
+## Process this file with automake to produce Makefile.in
+
+GIMP_DOC_LOGO = $(abs_top_srcdir)/data/images/gimp-logo.ong
+
+gimp-ui-3.0.toml: gimp-ui-3.0.toml.in
+ $(AM_V_GEN) sed \
+ -e 's/@GIMP_VERSION[@]/$(GIMP_VERSION)/' \
+ -e 's/@GIMP_LOGO[@]/$(GIMP_DOC_LOGO)/' \
+ $< $@
+
+# Markdown content files
+content_files = \
+ widget-gallery.md \
+ $(NULL)
+
+GimpUi-reference: $(top_builddir)/libgimp/GimpUi-@GIMP_API_VERSION@.gir
$(top_builddir)/libgimp/Gimp-@GIMP_API_VERSION@.gir $(content_files) gimp-ui-3.0.toml
+ $(GI_DOCGEN) \
+ generate \
+ --quiet \
+ --fatal-warnings \
+ --config=gimp-ui-3.0.toml \
+ --output-dir=$(abs_builddir)/Gimp-3.0 \
+ --no-namespace-dir \
+ --content-dir=$(abs_srcdir) \
+ --add-include-path=$(top_abs_builddir)/gimp \
+ $<
diff --git a/devel-docs/reference/gimp-ui/gimp-ui-3.0.toml.in
b/devel-docs/reference/gimp-ui/gimp-ui-3.0.toml.in
new file mode 100644
index 0000000000..69a315bacd
--- /dev/null
+++ b/devel-docs/reference/gimp-ui/gimp-ui-3.0.toml.in
@@ -0,0 +1,108 @@
+[library]
+namespace = "GimpUi"
+version = "@GIMP_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gimp/";
+repository_url = "https://gitlab.gnome.org/GNOME/gimp.git";
+website_url = "https://www.gimp.org";
+authors = "GIMP contributors"
+logo_url = "@GIMP_LOGO@"
+license = "GPL-3.0-or-later"
+description = "GIMP UI library"
+dependencies = [
+ 'Babl-0.1',
+ 'GLib-2.0',
+ 'GObject-2.0',
+ 'GdkPixbuf-2.0',
+ 'Gegl-0.4',
+ 'Gio-2.0',
+ 'Gtk-3.0',
+ 'cairo-1.0',
+]
+devhelp = true
+search_index = true
+
+ [dependencies."Babl-0.1"]
+ name = "Babl"
+ description = "Pixel encoding and color space conversion engine"
+ docs_url = "https://gegl.org/babl";
+
+ [dependencies."GLib-2.0"]
+ name = "GLib"
+ description = "C Utility Library"
+ docs_url = "https://developer.gnome.org/glib/stable";
+
+ [dependencies."GObject-2.0"]
+ name = "GObject"
+ description = "The base type system library"
+ docs_url = "https://developer.gnome.org/gobject/stable";
+
+ [dependencies."GdkPixbuf-2.0"]
+ name = "GdkPixbuf"
+ description = "Image loading and scaling"
+ docs_url = "https://docs.gtk.org/gdk-pixbuf/";
+
+ [dependencies."Gegl-0.4"]
+ name = "Gegl"
+ description = "Generic Graphics Library"
+ docs_url = "https://gegl.org/";
+
+ [dependencies."Gio-2.0"]
+ name = "Gio"
+ description = "GObject interfaces and objects"
+ docs_url = "https://developer.gnome.org/gio/stable";
+
+ [dependencies."Gtk-3.0"]
+ name = "GTK"
+ description = "The GTK toolkit"
+ docs_url = "https://developer.gnome.org/gtk3/stable";
+
+ [dependencies."cairo-1.0"]
+ name = "Cairo"
+ description = "A 2D graphics library with support for multiple output devices"
+ docs_url = "https://www.cairographics.org/manual/";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gimp/-/blob/master/";
+
+[extra]
+content_files = [
+ 'widget-gallery.md',
+]
+content_images = [
+ 'images/browser.png',
+ 'images/busy-box.png',
+ 'images/button.png',
+ 'images/chain-button.png',
+ 'images/color-area.png',
+ 'images/color-button.png',
+ 'images/color-hex-entry.png',
+ 'images/color-notebook.png',
+ 'images/color-profile-combo-box.png',
+ 'images/color-profile-view.png',
+ 'images/color-scale.png',
+ 'images/color-scales.png',
+ 'images/color-select.png',
+ 'images/color-selection.png',
+ 'images/dialog.png',
+ 'images/enum-combo-box.png',
+ 'images/enum-label.png',
+ 'images/file-entry.png',
+ 'images/frame.png',
+ 'images/hint-box.png',
+ 'images/int-combo-box.png',
+ 'images/memsize-entry.png',
+ 'images/number-pair-entry.png',
+ 'images/offset-area.png',
+ 'images/page-selector.png',
+ 'images/path-editor.png',
+ 'images/pick-button.png',
+ 'images/preview-area.png',
+ 'images/ruler.png',
+ 'images/string-combo-box.png',
+ 'images/unit-combo-box.png',
+]
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-browser.png
b/devel-docs/reference/gimp-ui/images/browser.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-browser.png
rename to devel-docs/reference/gimp-ui/images/browser.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-busy-box.png
b/devel-docs/reference/gimp-ui/images/busy-box.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-busy-box.png
rename to devel-docs/reference/gimp-ui/images/busy-box.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-button.png
b/devel-docs/reference/gimp-ui/images/button.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-button.png
rename to devel-docs/reference/gimp-ui/images/button.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-chain-button.png
b/devel-docs/reference/gimp-ui/images/chain-button.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-chain-button.png
rename to devel-docs/reference/gimp-ui/images/chain-button.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-area.png
b/devel-docs/reference/gimp-ui/images/color-area.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-area.png
rename to devel-docs/reference/gimp-ui/images/color-area.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-button.png
b/devel-docs/reference/gimp-ui/images/color-button.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-button.png
rename to devel-docs/reference/gimp-ui/images/color-button.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-hex-entry.png
b/devel-docs/reference/gimp-ui/images/color-hex-entry.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-hex-entry.png
rename to devel-docs/reference/gimp-ui/images/color-hex-entry.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-notebook.png
b/devel-docs/reference/gimp-ui/images/color-notebook.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-notebook.png
rename to devel-docs/reference/gimp-ui/images/color-notebook.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-profile-combo-box.png
b/devel-docs/reference/gimp-ui/images/color-profile-combo-box.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-profile-combo-box.png
rename to devel-docs/reference/gimp-ui/images/color-profile-combo-box.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-profile-view.png
b/devel-docs/reference/gimp-ui/images/color-profile-view.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-profile-view.png
rename to devel-docs/reference/gimp-ui/images/color-profile-view.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-scale.png
b/devel-docs/reference/gimp-ui/images/color-scale.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-scale.png
rename to devel-docs/reference/gimp-ui/images/color-scale.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-scales.png
b/devel-docs/reference/gimp-ui/images/color-scales.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-scales.png
rename to devel-docs/reference/gimp-ui/images/color-scales.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-select.png
b/devel-docs/reference/gimp-ui/images/color-select.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-select.png
rename to devel-docs/reference/gimp-ui/images/color-select.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-color-selection.png
b/devel-docs/reference/gimp-ui/images/color-selection.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-color-selection.png
rename to devel-docs/reference/gimp-ui/images/color-selection.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-dialog.png
b/devel-docs/reference/gimp-ui/images/dialog.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-dialog.png
rename to devel-docs/reference/gimp-ui/images/dialog.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-enum-combo-box.png
b/devel-docs/reference/gimp-ui/images/enum-combo-box.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-enum-combo-box.png
rename to devel-docs/reference/gimp-ui/images/enum-combo-box.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-enum-label.png
b/devel-docs/reference/gimp-ui/images/enum-label.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-enum-label.png
rename to devel-docs/reference/gimp-ui/images/enum-label.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-file-entry.png
b/devel-docs/reference/gimp-ui/images/file-entry.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-file-entry.png
rename to devel-docs/reference/gimp-ui/images/file-entry.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-frame.png
b/devel-docs/reference/gimp-ui/images/frame.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-frame.png
rename to devel-docs/reference/gimp-ui/images/frame.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-hint-box.png
b/devel-docs/reference/gimp-ui/images/hint-box.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-hint-box.png
rename to devel-docs/reference/gimp-ui/images/hint-box.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-int-combo-box.png
b/devel-docs/reference/gimp-ui/images/int-combo-box.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-int-combo-box.png
rename to devel-docs/reference/gimp-ui/images/int-combo-box.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-memsize-entry.png
b/devel-docs/reference/gimp-ui/images/memsize-entry.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-memsize-entry.png
rename to devel-docs/reference/gimp-ui/images/memsize-entry.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-number-pair-entry.png
b/devel-docs/reference/gimp-ui/images/number-pair-entry.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-number-pair-entry.png
rename to devel-docs/reference/gimp-ui/images/number-pair-entry.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-offset-area.png
b/devel-docs/reference/gimp-ui/images/offset-area.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-offset-area.png
rename to devel-docs/reference/gimp-ui/images/offset-area.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-page-selector.png
b/devel-docs/reference/gimp-ui/images/page-selector.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-page-selector.png
rename to devel-docs/reference/gimp-ui/images/page-selector.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-path-editor.png
b/devel-docs/reference/gimp-ui/images/path-editor.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-path-editor.png
rename to devel-docs/reference/gimp-ui/images/path-editor.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-pick-button.png
b/devel-docs/reference/gimp-ui/images/pick-button.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-pick-button.png
rename to devel-docs/reference/gimp-ui/images/pick-button.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-preview-area.png
b/devel-docs/reference/gimp-ui/images/preview-area.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-preview-area.png
rename to devel-docs/reference/gimp-ui/images/preview-area.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-ruler.png
b/devel-docs/reference/gimp-ui/images/ruler.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-ruler.png
rename to devel-docs/reference/gimp-ui/images/ruler.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-string-combo-box.png
b/devel-docs/reference/gimp-ui/images/string-combo-box.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-string-combo-box.png
rename to devel-docs/reference/gimp-ui/images/string-combo-box.png
diff --git a/devel-docs/libgimpwidgets/images/gimp-widget-unit-combo-box.png
b/devel-docs/reference/gimp-ui/images/unit-combo-box.png
similarity index 100%
rename from devel-docs/libgimpwidgets/images/gimp-widget-unit-combo-box.png
rename to devel-docs/reference/gimp-ui/images/unit-combo-box.png
diff --git a/devel-docs/reference/gimp-ui/meson.build b/devel-docs/reference/gimp-ui/meson.build
new file mode 100644
index 0000000000..aafc456bbc
--- /dev/null
+++ b/devel-docs/reference/gimp-ui/meson.build
@@ -0,0 +1,37 @@
+# Extra markdown files
+gimp_ui_doc_content_files = [
+ 'widget-gallery.md',
+]
+
+gimp_ui_doc_toml = configure_file(
+ input: 'gimp-ui-3.0.toml.in',
+ output: '@BASENAME@',
+ configuration: {
+ 'GIMP_VERSION': gimp_version,
+ 'GIMP_LOGO': gimp_logo_dir / 'gimp-logo.png',
+ },
+)
+
+gimp_ui_docs = custom_target('gimp-ui-docs',
+ input: libgimpui_gir[0],
+ output: 'GimpUi-@0@'.format(gimp_api_version),
+ command: [
+ gi_docgen,
+ 'generate',
+ '--quiet',
+ '--fatal-warnings',
+ '--config', gimp_ui_doc_toml,
+ '--output-dir=@OUTPUT@',
+ '--no-namespace-dir',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '--add-include-path=@0@'.format(meson.build_root() / 'gimp'),
+ '@INPUT@',
+ ],
+ depend_files: [
+ gimp_ui_doc_toml,
+ gimp_ui_doc_content_files,
+ ],
+ build_by_default: true,
+ install: true,
+ install_dir: get_option('datadir') / 'doc',
+)
diff --git a/devel-docs/reference/gimp-ui/widget-gallery.md b/devel-docs/reference/gimp-ui/widget-gallery.md
new file mode 100644
index 0000000000..b436f2c07a
--- /dev/null
+++ b/devel-docs/reference/gimp-ui/widget-gallery.md
@@ -0,0 +1,36 @@
+Title: Widget gallery
+
+Widget gallery
+==============
+
+[](class.Browser.html)
+[](class.Button.html)
+[](class.BusyBox.html)
+[](class.ChainButton.html)
+[](class.ColorArea.html)
+[](class.ColorButton.html)
+[](class.ColorHexEntry.html)
+[](class.ColorNotebook.html)
+[](class.ColorScale.html)
+[](class.ColorScales.html)
+[](class.ColorSelect.html)
+[](class.ColorSelection.html)
+[](class.ColorProfileComboBox.html)
+[](class.ColorProfileView.html)
+[](class.Dialog.html)
+[](class.EnumComboBox.html)
+[](class.EnumLabel.html)
+[](class.FileEntry.html)
+[](class.Frame.html)
+[](class.HintBox.html)
+[](class.IntComboBox.html)
+[](class.MemsizeEntry.html)
+[](class.NumberPairEntry.html)
+[](class.OffsetArea.html)
+[](class.PageSelector.html)
+[](class.PathEditor.html)
+[](class.PickButton.html)
+[](class.PreviewArea.html)
+[](class.Ruler.html)
+[](class.StringComboBox.html)
+[](class.UnitComboBox.html)
diff --git a/devel-docs/reference/gimp/Makefile.am b/devel-docs/reference/gimp/Makefile.am
new file mode 100644
index 0000000000..c5bade5445
--- /dev/null
+++ b/devel-docs/reference/gimp/Makefile.am
@@ -0,0 +1,24 @@
+## Process this file with automake to produce Makefile.in
+
+GIMP_DOC_LOGO = $(abs_top_srcdir)/data/images/gimp-logo.ong
+
+gimp-3.0.toml: gimp-3.0.toml.in
+ $(AM_V_GEN) sed \
+ -e 's/@GIMP_VERSION[@]/$(GIMP_VERSION)/' \
+ -e 's/@GIMP_LOGO[@]/$(GIMP_DOC_LOGO)/' \
+ $< $@
+
+# Markdown content files
+content_files = \
+ $(NULL)
+
+Gimp-reference: $(top_builddir)/libgimp/Gimp-@GIMP_API_VERSION@.gir $(content_files) gimp-3.0.toml
+ $(GI_DOCGEN) \
+ generate \
+ --quiet \
+ --fatal-warnings \
+ --config=gimp-3.0.toml \
+ --output-dir=$(abs_builddir)/Gimp-3.0 \
+ --no-namespace-dir \
+ --content-dir=$(abs_srcdir) \
+ $<
diff --git a/devel-docs/reference/gimp/gimp-3.0.toml.in b/devel-docs/reference/gimp/gimp-3.0.toml.in
new file mode 100644
index 0000000000..f25364c830
--- /dev/null
+++ b/devel-docs/reference/gimp/gimp-3.0.toml.in
@@ -0,0 +1,74 @@
+[library]
+namespace = "Gimp"
+version = "@GIMP_VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/gimp/";
+repository_url = "https://gitlab.gnome.org/GNOME/gimp.git";
+website_url = "https://www.gimp.org";
+authors = "GIMP contributors"
+logo_url = "@GIMP_LOGO_PATH@"
+license = "GPL-3.0-or-later"
+description = "GIMP library"
+dependencies = [
+ 'Babl-0.1',
+ 'GLib-2.0',
+ 'GObject-2.0',
+ 'GdkPixbuf-2.0',
+ 'Gegl-0.4',
+ 'Gio-2.0',
+ 'Gtk-3.0',
+ 'cairo-1.0',
+]
+devhelp = true
+search_index = true
+
+ [dependencies."Babl-0.1"]
+ name = "Babl"
+ description = "Pixel encoding and color space conversion engine"
+ docs_url = "https://gegl.org/babl";
+
+ [dependencies."GLib-2.0"]
+ name = "GLib"
+ description = "C Utility Library"
+ docs_url = "https://developer.gnome.org/glib/stable";
+
+ [dependencies."GObject-2.0"]
+ name = "GObject"
+ description = "The base type system library"
+ docs_url = "https://developer.gnome.org/gobject/stable";
+
+ [dependencies."GdkPixbuf-2.0"]
+ name = "GdkPixbuf"
+ description = "Image loading and scaling"
+ docs_url = "https://docs.gtk.org/gdk-pixbuf/";
+
+ [dependencies."Gegl-0.4"]
+ name = "Gegl"
+ description = "Generic Graphics Library"
+ docs_url = "https://gegl.org/";
+
+ [dependencies."Gio-2.0"]
+ name = "Gio"
+ description = "GObject interfaces and objects"
+ docs_url = "https://developer.gnome.org/gio/stable";
+
+ [dependencies."Gtk-3.0"]
+ name = "GTK"
+ description = "The GTK toolkit"
+ docs_url = "https://developer.gnome.org/gtk3/stable";
+
+ [dependencies."cairo-1.0"]
+ name = "Cairo"
+ description = "A 2D graphics library with support for multiple output devices"
+ docs_url = "https://www.cairographics.org/manual/";
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/gimp/-/blob/master/";
+
+[extra]
+content_files = [
+]
diff --git a/devel-docs/reference/gimp/meson.build b/devel-docs/reference/gimp/meson.build
new file mode 100644
index 0000000000..aa0af4ac48
--- /dev/null
+++ b/devel-docs/reference/gimp/meson.build
@@ -0,0 +1,35 @@
+# Extra markdown files
+gimp_doc_content_files = [
+]
+
+gimp_doc_toml = configure_file(
+ input: 'gimp-3.0.toml.in',
+ output: '@BASENAME@',
+ configuration: {
+ 'GIMP_VERSION': gimp_version,
+ 'GIMP_LOGO': gimp_logo_dir / 'gimp-logo.png',
+ },
+)
+
+gimp_docs = custom_target('gimp-docs',
+ input: libgimp_gir[0],
+ output: 'Gimp-@0@'.format(gimp_api_version),
+ command: [
+ gi_docgen,
+ 'generate',
+ '--quiet',
+ '--fatal-warnings',
+ '--config', gimp_doc_toml,
+ '--output-dir=@OUTPUT@',
+ '--no-namespace-dir',
+ '--content-dir=@0@'.format(meson.current_source_dir()),
+ '@INPUT@',
+ ],
+ depend_files: [
+ gimp_doc_toml,
+ gimp_doc_content_files,
+ ],
+ build_by_default: true,
+ install: true,
+ install_dir: get_option('datadir') / 'doc',
+)
diff --git a/devel-docs/reference/meson.build b/devel-docs/reference/meson.build
new file mode 100644
index 0000000000..e885a51a21
--- /dev/null
+++ b/devel-docs/reference/meson.build
@@ -0,0 +1,4 @@
+gi_docgen = find_program('gi-docgen')
+
+subdir('gimp')
+subdir('gimp-ui')
diff --git a/libgimp/gimpplugin.c b/libgimp/gimpplugin.c
index 86fd4975f4..f3ce17f1bc 100644
--- a/libgimp/gimpplugin.c
+++ b/libgimp/gimpplugin.c
@@ -38,70 +38,62 @@
/**
- * SECTION: gimpplugin
- * @title: GimpPlugIn
- * @short_description: The base class for plug-ins to derive from
+ * GimpPlugIn:
*
- * The base class for plug-ins to derive from. #GimpPlugIn manages the
- * plug-in's #GimpProcedure objects. The procedures a plug-in
- * implements are registered with GIMP by returning a #GList of their
- * names from either #GimpPlugInClass.query_procedures() or
- * #GimpPlugInClass.init_procedures().
+ * The base class for plug-ins to derive from.
*
- * Every GIMP plug-in has to implement a #GimpPlugIn subclass and make
- * it known to the libgimp infrastructure and the main GIMP
- * application by passing its #GType to GIMP_MAIN().
+ * GimpPlugIn manages the plug-in's [class@Procedure] objects. The procedures a
+ * plug-in implements are registered with GIMP by returning a list of their
+ * names from either [vfunc@GimpPlugIn.query_procedures] or
+ * [vfunc@GimpPlugIn.init_procedures].
*
- * GIMP_MAIN() passes the 'argc' and 'argv' of the platform's main()
- * function, along with the #GType, to gimp_main(), which creates an
- * instance of the plug-in's #GimpPlugIn subclass and calls its
- * virtual functions, depending on how the plug-in was called by GIMP.
+ * Every GIMP plug-in has to be implemented as a subclass and make it known to
+ * the libgimp infrastructure and the main GIMP application by passing its
+ * `GType` to [func@MAIN].
*
- * There are three different ways GIMP calls a plug-in, "query",
- * "init" and "run".
+ * [func@MAIN] passes the 'argc' and 'argv' of the platform's main() function,
+ * along with the `GType`, to [func@main], which creates an instance of the
+ * plug-in's `GimpPlugIn` subclass and calls its virtual functions, depending
+ * on how the plug-in was called by GIMP.
*
- * The plug-in is called in "query" mode once after it was installed,
- * or when the cached plug-in information in the config file
- * "pluginrc" needs to be recreated. In "query" mode,
- * #GimpPlugInClass.query_procedures() is called and returns a #GList
- * of procedure names the plug-in implements. This is the "normal"
- * place to register procedures, because the existence of most
- * procedures doesn't depend on things that change between GIMP
- * sessions.
+ * There are 3 different ways GIMP calls a plug-in: "query", "init" and "run".
+ *
+ * The plug-in is called in "query" mode once after it was installed, or when
+ * the cached plug-in information in the config file "pluginrc" needs to be
+ * recreated. In "query" mode, [vfunc@GimpPlugIn.query_procedures] is called
+ * and returns a list of procedure names the plug-in implements. This is the
+ * "normal" place to register procedures, because the existence of most
+ * procedures doesn't depend on things that change between GIMP sessions.
*
* The plug-in is called in "init" mode at each GIMP startup, and
- * #GimpPlugInClass.init_procedures() is called and returns a #GList
- * of procedure names this plug-in implements. This only happens if
- * the plug-in actually implements
- * #GimpPlugInClass.init_procedures(). A plug-in only needs to
- * implement #GimpPlugInClass.init_procedures() if the existence of
- * its procedures can change between GIMP sessions, for example if
- * they depend on the presence of external tools, or hardware like
- * scanners, or online services, or whatever variable circumstances.
+ * [vfunc@PlugIn.init_procedures] is called and returns a list of procedure
+ * names this plug-in implements. This only happens if the plug-in actually
+ * implements [vfunc@GimpPlugIn.init_procedures]. A plug-in only needs to
+ * implement init_procedures if the existence of its procedures can change
+ * between GIMP sessions, for example if they depend on the presence of
+ * external tools, or hardware like scanners, or online services, or whatever
+ * variable circumstances.
*
- * In order to register the plug-in's procedures with the main GIMP
- * application in the plug-in's "query" and "init" modes, #GimpPlugIn
- * calls #GimpPlugInClass.create_procedure() on all procedure names in
- * the exact order of the #GList returned by
- * #GimpPlugInClass.query_procedures() or
- * #GimpPlugInClass.init_procedures() and then registers the returned
- * #GimpProcedure using #GimpProcedureClass.register().
+ * In order to register the plug-in's procedures with the main GIMP application
+ * in the plug-in's "query" and "init" modes, [class@PlugIn] calls
+ * [vfunc@PlugIn.create_procedure] on all procedure names in the exact order of
+ * the list returned by [vfunc@PlugIn.query_procedures] or
+ * [vfunc@PlugIn.init_procedures] and then registers the returned
+ * [class@Procedure].
*
- * The plug-in is called in "run" mode whenever one of the procedures
- * it implements is called by either the main GIMP application or any
- * other plug-in. In "run" mode, one of the procedure names returned
- * by #GimpPlugInClass.query_procedures() or
- * #GimpPlugInClass.init_procedures() is passed to
- * #GimpPlugInClass.create_procedure() which must return a
- * #GimpProcedure for the passed name. The procedure is then executed
- * by calling gimp_procedure_run().
+ * The plug-in is called in "run" mode whenever one of the procedures it
+ * implements is called by either the main GIMP application or any other
+ * plug-in. In "run" mode, one of the procedure names returned by
+ * [vfunc@PlugIn.query_procedures] or [vfunc@PlugIn.init_procedures] is passed
+ * to [vfunc@PlugIn.create_procedure] which must return a [class@Procedure] for
+ * the passed name. The procedure is then executed by calling
+ * [method Procedure run].
*
- * In any of the three modes, #GimpPlugInClass.quit() is called before
- * the plug-in process exits, so the plug-in can perform whatever
- * cleanup necessary.
+ * In any of the three modes, [vfunc PlugIn quit] is called before the plug-in
+ * process exits, so the plug-in can perform whatever cleanup necessary.
*
* Since: 3.0
- **/
+ */
#define WRITE_BUFFER_SIZE 1024
@@ -230,6 +222,11 @@ gimp_plug_in_class_init (GimpPlugInClass *klass)
object_class->set_property = gimp_plug_in_set_property;
object_class->get_property = gimp_plug_in_get_property;
+ /**
+ * GimpPlugIn:read-channel:
+ *
+ * The [struct@GLib.IOChannel] to read from GIMP
+ */
props[PROP_READ_CHANNEL] =
g_param_spec_boxed ("read-channel",
"Read channel",
@@ -238,6 +235,11 @@ gimp_plug_in_class_init (GimpPlugInClass *klass)
GIMP_PARAM_READWRITE |
G_PARAM_CONSTRUCT_ONLY);
+ /**
+ * GimpPlugIn:write-channel:
+ *
+ * The [struct@GLib.IOChannel] to write to GIMP
+ */
props[PROP_WRITE_CHANNEL] =
g_param_spec_boxed ("write-channel",
"Write channel",
@@ -378,7 +380,7 @@ gimp_plug_in_get_property (GObject *object,
* gimp_plug_in_set_translation_domain:
* @plug_in: A #GimpPlugIn.
* @domain_name: The name of the textdomain (must be unique).
- * @domain_path: (nullable): A #GFile pointing to the compiled message catalog
+ * @domain_path: (nullable): A file pointing to the compiled message catalog
* (may be %NULL).
*
* Sets a textdomain for localisation for the @plug_in.
@@ -392,7 +394,7 @@ gimp_plug_in_get_property (GObject *object,
* location.
*
* This function can only be called in the
- * #GimpPlugInClass.query_procedures() function of a plug-in.
+ * [vfunc@PlugIn.query_procedures] function of a plug-in.
*
* Since: 3.0
**/
@@ -420,13 +422,13 @@ gimp_plug_in_set_translation_domain (GimpPlugIn *plug_in,
* Set a help domain and path for the @plug_in.
*
* This function registers user documentation for the calling plug-in
- * with the GIMP help system. The domain_uri parameter points to the
+ * with the GIMP help system. The @domain_uri parameter points to the
* root directory where the plug-in help is installed. For each
* supported language there should be a file called 'gimp-help.xml'
* that maps the help IDs to the actual help files.
*
* This function can only be called in the
- * #GimpPlugInClass.query_procedures() function of a plug-in.
+ * [vfunc@PlugIn.query_procedures] function of a plug-in.
*
* Since: 3.0
**/
@@ -492,19 +494,19 @@ gimp_plug_in_add_menu_branch (GimpPlugIn *plug_in,
*
* This function adds a temporary procedure to @plug_in. It is usually
* called from a %GIMP_PDB_PROC_TYPE_EXTENSION procedure's
- * #GimpProcedureClass.run().
+ * [vfunc Procedure run].
*
* A temporary procedure is a procedure which is only available while
* one of your plug-in's "real" procedures is running.
*
- * The procedure's type <emphasis>must</emphasis> be
+ * The procedure's type _must_ be
* %GIMP_PDB_PROC_TYPE_TEMPORARY or the function will fail.
*
* NOTE: Normally, plug-in communication is triggered by the plug-in
* and the GIMP core only responds to the plug-in's requests. You must
* explicitly enable receiving of temporary procedure run requests
- * using either gimp_plug_in_extension_enable() or
- * gimp_plug_in_extension_process(). See this functions' documentation
+ * using either [method@PlugIn.extension_enable] or
+ * [method@PlugIn.extension_process]. See their respective documentation
* for details.
*
* Since: 3.0
@@ -528,7 +530,7 @@ gimp_plug_in_add_temp_procedure (GimpPlugIn *plug_in,
/**
* gimp_plug_in_remove_temp_procedure:
* @plug_in: A #GimpPlugIn
- * @procedure_name: The name of a #GimpProcedure added to @plug_in.
+ * @procedure_name: The name of a [class@Procedure] added to @plug_in.
*
* This function removes a temporary procedure from @plug_in by the
* procedure's @procedure_name.
@@ -559,10 +561,10 @@ gimp_plug_in_remove_temp_procedure (GimpPlugIn *plug_in,
/**
* gimp_plug_in_get_temp_procedures:
- * @plug_in: A #GimpPlugIn
+ * @plug_in: A plug-in
*
* This function retrieves the list of temporary procedure of @plug_in as
- * added with gimp_plug_in_add_temp_procedure().
+ * added with [method@PlugIn.add_temp_procedure].
*
* Returns: (transfer none) (element-type GimpProcedure): The list of
* procedures.
@@ -580,7 +582,7 @@ gimp_plug_in_get_temp_procedures (GimpPlugIn *plug_in)
/**
* gimp_plug_in_get_temp_procedure:
* @plug_in: A #GimpPlugIn
- * @procedure_name: The name of a #GimpProcedure added to @plug_in.
+ * @procedure_name: The name of a [class@Procedure] added to @plug_in.
*
* This function retrieves a temporary procedure from @plug_in by the
* procedure's @procedure_name.
@@ -611,7 +613,7 @@ gimp_plug_in_get_temp_procedure (GimpPlugIn *plug_in,
/**
* gimp_plug_in_extension_enable:
- * @plug_in: A #GimpPlugIn
+ * @plug_in: A plug-in
*
* Enables asynchronous processing of messages from the main GIMP
* application.
@@ -622,18 +624,18 @@ gimp_plug_in_get_temp_procedure (GimpPlugIn *plug_in,
* plug-in are just answers to requests the plug-in made.
*
* If the plug-in however registered temporary procedures using
- * gimp_plug_in_add_temp_procedure(), it needs to be able to receive
+ * [method@PlugIn.add_temp_procedure], it needs to be able to receive
* requests to execute them. Usually this will be done by running
- * gimp_plug_in_extension_process() in an endless loop.
+ * [method@PlugIn.extension_process] in an endless loop.
*
- * If the plug-in cannot use gimp_plug_in_extension_process(), i.e. if
- * it has a GUI and is hanging around in a #GMainLoop, it must call
- * gimp_plug_in_extension_enable().
+ * If the plug-in cannot use [method@PlugIn.extension_process], i.e. if
+ * it has a GUI and is hanging around in a [class@GLib.MainLoop], it must call
+ * [method@PlugIn.extension_enable].
*
* Note that the plug-in does not need to be a
- * #GIMP_PDB_PROC_TYPE_EXTENSION to register temporary procedures.
+ * [const@PDBProcType.EXTENSION] to register temporary procedures.
*
- * See also: gimp_plug_in_add_temp_procedure().
+ * See also: [method@PlugIn.add_temp_procedure].
*
* Since: 3.0
**/
@@ -653,7 +655,7 @@ gimp_plug_in_extension_enable (GimpPlugIn *plug_in)
/**
* gimp_plug_in_extension_process:
- * @plug_in: A #GimpPlugIn.
+ * @plug_in: A plug-in.
* @timeout: The timeout (in ms) to use for the select() call.
*
* Processes one message sent by GIMP and returns.
@@ -662,10 +664,10 @@ gimp_plug_in_extension_enable (GimpPlugIn *plug_in)
* gimp_procedure_extension_ready() to process requests for running
* temporary procedures.
*
- * See gimp_plug_in_extension_enable() for an asynchronous way of
+ * See [method@PlugIn.extension_enable] for an asynchronous way of
* doing the same if running an endless loop is not an option.
*
- * See also: gimp_plug_in_add_temp_procedure().
+ * See also: [method@PlugIn.add_temp_procedure].
*
* Since: 3.0
**/
@@ -736,7 +738,7 @@ gimp_plug_in_extension_process (GimpPlugIn *plug_in,
/**
* gimp_plug_in_set_pdb_error_handler:
- * @plug_in: A #GimpPlugIn
+ * @plug_in: A plug-in
* @handler: Who is responsible for handling procedure call errors.
*
* Sets an error handler for procedure calls.
@@ -763,7 +765,7 @@ gimp_plug_in_set_pdb_error_handler (GimpPlugIn *plug_in,
/**
* gimp_plug_in_get_pdb_error_handler:
- * @plug_in: A #GimpPlugIn
+ * @plug_in: A plug-in
*
* Retrieves the active error handler for procedure calls.
*
diff --git a/libgimp/gimpplugin.h b/libgimp/gimpplugin.h
index 9cc9c521a0..14f20a8849 100644
--- a/libgimp/gimpplugin.h
+++ b/libgimp/gimpplugin.h
@@ -53,41 +53,10 @@ struct _GimpPlugIn
/**
* GimpPlugInClass:
- * @query_procedures: This method can be overridden by all plug-ins to
- * return a newly allocated #GList of allocated strings naming the
- * procedures registered by this plug-in. See documentation of
- * #GimpPlugInClass.init_procedures() for differences.
- * @init_procedures: This method can be overridden by all plug-ins to
- * return a newly allocated #GList of allocated strings naming
- * procedures registered by this plug-in.
- * It is different from #GimpPlugInClass.query_procedures() in that
- * init happens at every startup, whereas query happens only once in
- * the life of a plug-in (right after installation or update). Hence
- * #GimpPlugInClass.init_procedures() typically returns procedures
- * dependent to runtime conditions (such as the presence of a
- * third-party tool), whereas #GimpPlugInClass.query_procedures()
- * would usually return procedures that are always available
- * unconditionally.
- * Most of the time, you only want to override
- * #GimpPlugInClass.query_procedures() and leave
- * #GimpPlugInClass.init_procedures() untouched.
- * @create_procedure: This method must be overridden by all plug-ins
- * and return a newly allocated #GimpProcedure named @name. It will
- * be called for every @name as returned by
- * #GimpPlugInClass.query_procedures() and
- * #GimpPlugInClass.init_procedures() so care must be taken to
- * handle them all.
- * Upon procedure registration, #GimpPlugInClass.create_procedure()
- * will be called in the order of the lists returned by
- * #GimpPlugInClass.query_procedures() and
- * #GimpPlugInClass.init_procedures()
- * @quit: This method can be overridden by a plug-in which needs to
- * perform some actions upon quitting.
*
* A class which every plug-in should subclass, while overriding
- * #GimpPlugInClass.query_procedures() and/or
- * #GimpPlugInClass.init_procedures(), as well as
- * #GimpPlugInClass.create_procedure().
+ * [vfunc@PlugIn.query_procedures] and/or [vfunc@PlugIn.init_procedures], as
+ * well as [vfunc@PlugIn.create_procedure].
*
* Since: 3.0
**/
@@ -99,17 +68,33 @@ struct _GimpPlugInClass
* GimpPlugInClass::query_procedures:
* @plug_in: a #GimpPlugIn.
*
- * Returns: (element-type gchar*) (transfer full):
- * the names of the procedures registered by @plug_in.
- **/
+ * This method can be overridden by all plug-ins to return a newly allocated
+ * list of allocated strings naming the procedures registered by this
+ * plug-in. See documentation of [vfunc@PlugIn.init_procedures] for
+ * differences.
+ *
+ * Returns: (element-type gchar*) (transfer full): the names of the procedures registered by @plug_in.
+ */
GList * (* query_procedures) (GimpPlugIn *plug_in);
/**
* GimpPlugInClass::init_procedures:
* @plug_in: a #GimpPlugIn.
*
- * Returns: (element-type gchar*) (transfer full):
- * the names of the procedures registered by @plug_in.
+ * This method can be overridden by all plug-ins to return a newly allocated
+ * list of allocated strings naming procedures registered by this plug-in.
+ * It is different from [vfunc@PlugIn.query_procedures] in that init happens
+ * at every startup, whereas query happens only once in the life of a plug-in
+ * (right after installation or update). Hence [vfunc@PlugIn.init_procedures]
+ * typically returns procedures dependent to runtime conditions (such as the
+ * presence of a third-party tool), whereas [vfunc@PlugIn.query_procedures]
+ * would usually return procedures that are always available unconditionally.
+ *
+ * Most of the time, you only want to override
+ * [vfunc@PlugIn.query_procedures] and leave [vfunc@PlugIn.init_procedures]
+ * untouched.
+ *
+ * Returns: (element-type gchar*) (transfer full): the names of the procedures registered by @plug_in.
**/
GList * (* init_procedures) (GimpPlugIn *plug_in);
@@ -118,16 +103,28 @@ struct _GimpPlugInClass
* @plug_in: a #GimpPlugIn.
* @procedure_name: procedure name.
*
- * Returns: (transfer full):
- * the procedure to be registered or executed by @plug_in.
- **/
+ * This method must be overridden by all plug-ins and return a newly
+ * allocated #GimpProcedure named @name.
+ *
+ * This method will be called for every @name as returned by
+ * [vfunc@PlugIn.query_procedures] and [vfunc@PlugIn.init_procedures] so care
+ * must be taken to handle them all. Upon procedure registration,
+ * [vfunc@PlugIn.create_procedure] will be called in the order of the lists
+ * returned by [vfunc@PlugIn.query_procedures] and
+ * [vfunc@PlugIn.init_procedures]
+ *
+ * Returns: (transfer full): the procedure to be registered or executed by @plug_in.
+ */
GimpProcedure * (* create_procedure) (GimpPlugIn *plug_in,
const gchar *procedure_name);
/**
* GimpPlugInClass::quit:
* @plug_in: a #GimpPlugIn.
- **/
+ *
+ * This method can be overridden by a plug-in which needs to perform some
+ * actions upon quitting.
+ */
void (* quit) (GimpPlugIn *plug_in);
/* Padding for future expansion */
diff --git a/meson_options.txt b/meson_options.txt
index 6bb1c69afc..0f77c71850 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -52,8 +52,7 @@ option('xcursor', type: 'feature', value: 'auto', description: 'Xcurso
option('xpm', type: 'feature', value: 'auto', description: 'XPM support')
option('headless-tests', type: 'feature', value: 'auto', description: 'Use xvfb-run/dbus-run-session for
UI-dependent automatic tests')
-option('gtk-doc', type: 'boolean', value: true, description: 'Build developer documentation')
-option('gtk-doc-app', type: 'boolean', value: false, description: 'Build developer documentation for
app')
+option('gi-docgen', type: 'boolean', value: true, description: 'Build developer documentation
(uses gi-docgen)')
option('g-ir-doc', type: 'boolean', value: false, description: 'Build developer documentation for
introspected API')
option('linux-input', type: 'feature', value: 'auto', description: 'Linux input event controller
module')
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
