gplugin/gplugin

Merge the move to gtk-doc
develop
2018-05-05, Gary Kramlich
93ba1dbb604a
Parents 46f92694369c4cabede88ce7
Children 213973fd5975
Merge the move to gtk-doc
22 files changed, 510 insertions(+), 53 deletions(-)
  • +33 -15
    gplugin-gtk/meson.build
  • +47 -0
    gplugin-gtk/reference/gplugin-gtk-docs.xml
  • +38 -0
    gplugin-gtk/reference/meson.build
  • +1 -0
    gplugin-gtk/reference/version.xml.in
  • +23 -0
    gplugin/gplugin-core.c
  • +8 -0
    gplugin/gplugin-enums.c.tmpl
  • +20 -2
    gplugin/gplugin-loader.c
  • +9 -0
    gplugin/gplugin-manager.c
  • +16 -0
    gplugin/gplugin-native-loader.c
  • +9 -0
    gplugin/gplugin-native-plugin.c
  • +10 -0
    gplugin/gplugin-options.c
  • +72 -23
    gplugin/gplugin-plugin-info.c
  • +22 -6
    gplugin/gplugin-plugin.c
  • +2 -0
    gplugin/gplugin-plugin.h
  • +54 -0
    gplugin/gplugin-version.c
  • +4 -4
    gplugin/gplugin-version.h.in
  • +11 -1
    gplugin/meson.build
  • +65 -0
    gplugin/reference/gplugin-docs.xml
  • +43 -0
    gplugin/reference/meson.build
  • +1 -0
    gplugin/reference/version.xml.in
  • +14 -0
    meson.build
  • +8 -2
    meson_options.txt
    • --- a/gplugin-gtk/meson.build Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin-gtk/meson.build Sat May 05 19:26:49 2018 -0500
    @@ -25,10 +25,10 @@
    GPLUGIN_GTK_PRIVATE_HEADERS = [
    ]
    -GPLUGIN_GTK_BUILT_SOURCES = [
    +GPLUGIN_GTK_PUBLIC_BUILT_SOURCES = [
    ]
    -GPLUGIN_GTK_BUILT_HEADERS = [
    +GPLUGIN_GTK_PUBLIC_BUILT_HEADERS = [
    ]
    ###############################################################################
    @@ -59,8 +59,8 @@
    GPLUGIN_GTK_HEADERS,
    GPLUGIN_GTK_PRIVATE_SOURCES,
    GPLUGIN_GTK_PRIVATE_HEADERS,
    - GPLUGIN_GTK_BUILT_SOURCES,
    - GPLUGIN_GTK_BUILT_HEADERS,
    + GPLUGIN_GTK_PUBLIC_BUILT_SOURCES,
    + GPLUGIN_GTK_PUBLIC_BUILT_HEADERS,
    c_args : ['-DGPLUGIN_GTK_COMPILATION', '-DG_LOG_DOMAIN="GPluginGtk"'],
    include_directories : toplevel_inc,
    dependencies : [gplugin_dep, GTK3],
    @@ -68,16 +68,13 @@
    install : true
    )
    -# install the normal includes into the gplugin-gtk subdirectory
    -install_headers(
    - GPLUGIN_GTK_HEADERS,
    - subdir : 'gplugin-1.0/gplugin-gtk'
    -)
    +gplugin_gtk_inc = include_directories('.')
    -# install the GtkBuilder files
    -install_data(
    - 'gplugin-gtk-plugin-info.ui',
    - install_dir : join_paths(get_option('datadir'), 'gplugin', 'gplugin-gtk')
    +gplugin_gtk_dep = declare_dependency(
    + include_directories: [toplevel_inc, gplugin_gtk_inc],
    + link_with : [gplugin, gplugin_gtk],
    + sources : GPLUGIN_GTK_PUBLIC_BUILT_HEADERS, # Ensure they're built before use.
    + dependencies : [GLIB, GOBJECT, GTK3],
    )
    pkgconfig.generate(
    @@ -98,8 +95,7 @@
    ###############################################################################
    gplugin_gtk_viewer = executable('gplugin-gtk-viewer',
    'gplugin-gtk-viewer.c',
    - link_with : [gplugin_gtk],
    - dependencies : [gplugin_dep, GTK3],
    + dependencies : [gplugin_dep, gplugin_gtk_dep],
    install : true
    )
    @@ -115,4 +111,26 @@
    install_dir : join_paths(get_option('mandir'), 'man1'))
    endif
    +###############################################################################
    +# Install Stuff
    +###############################################################################
    +# install the normal includes into the gplugin-gtk subdirectory
    +install_headers(
    + GPLUGIN_GTK_HEADERS,
    + subdir : 'gplugin-1.0/gplugin-gtk'
    +)
    +
    +# install the GtkBuilder files
    +install_data(
    + 'gplugin-gtk-plugin-info.ui',
    + install_dir : join_paths(get_option('datadir'), 'gplugin', 'gplugin-gtk')
    +)
    +
    +###############################################################################
    +# subdirectories
    +###############################################################################
    +if ENABLE_DOC
    + subdir('reference')
    +endif
    +
    endif # gtk3
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/gplugin-gtk/reference/gplugin-gtk-docs.xml Sat May 05 19:26:49 2018 -0500
    @@ -0,0 +1,47 @@
    +<?xml version="1.0"?>
    +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
    +
    +<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
    +<!ENTITY version SYSTEM "version.xml">
    +]>
    +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
    + <bookinfo>
    + <title>GPlugin Gtk+ Reference Manual</title>
    + <abstract>
    + <title>GPlugin Gtk+ &version;</title>
    + <para>
    + GPlugin Gtk+ is a GObject based library that implements a reusable plugin system that
    + supports loading plugins in other languages
    + via loaders. GPlugin also implements
    + dependencies among the plugins.
    + </para>
    + </abstract>
    + </bookinfo>
    +
    + <part id="object-hierarchy">
    + <title>Object Hierarchy</title>
    +
    + <xi:include href="xml/tree_index.sgml"/>
    + </part>
    +
    + <part id="API">
    + <title>API Reference</title>
    +
    + </part>
    +
    + <index id="api-index-full">
    + <title>Index</title>
    + <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
    + </index>
    + <index id="api-index-deprecated" role="deprecated">
    + <title>Index of deprecated symbols</title>
    + <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
    + </index>
    +<!-- <index id="api-index-2.11.0" role="2.11.0">
    + <title>Index of new symbols in 2.11.0</title>
    + <xi:include href="xml/api-index-2.11.0.xml"><xi:fallback /></xi:include>
    + </index>
    + -->
    + <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
    +</book>
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/gplugin-gtk/reference/meson.build Sat May 05 19:26:49 2018 -0500
    @@ -0,0 +1,38 @@
    +DOC_MODULE = 'gplugin-gtk'
    +
    +# Header files or dirs to ignore when scanning. Use base file/dir names
    +ignore_hfiles = [
    +]
    +ignore_hfiles += GPLUGIN_GTK_PRIVATE_HEADERS
    +
    +# Extra options to supply to gtkdoc-scan.
    +scan_args = [
    + '--deprecated-guards=GPLUGIN_GTK_DISABLE_DEPRECATED',
    + '--rebuild-types',
    + '--rebuild-sections',
    + '--ignore-headers=' + ' '.join(ignore_hfiles),
    +]
    +
    +# Extra options to supply to gtkdoc-mkdb.
    +mkdb_args = [
    + '--ignore-files=' + ' '.join(ignore_hfiles),
    +]
    +
    +gplugin_gtk_version_xml = configure_file(
    + input : 'version.xml.in',
    + output : 'version.xml',
    + configuration : version_conf)
    +
    +content_files = [
    +]
    +
    +gnome.gtkdoc(DOC_MODULE,
    + main_xml : DOC_MODULE + '-docs.xml',
    + src_dir : gplugin_gtk_inc,
    + dependencies : gplugin_gtk_dep,
    + install : true,
    + scan_args : scan_args,
    + mkdb_args : mkdb_args,
    + gobject_typesfile : DOC_MODULE + '.types',
    + content_files : content_files,
    +)
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/gplugin-gtk/reference/version.xml.in Sat May 05 19:26:49 2018 -0500
    @@ -0,0 +1,1 @@
    +@GPLUGIN_GTK_VERSION@
    --- a/gplugin/gplugin-core.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-core.c Sat May 05 19:26:49 2018 -0500
    @@ -23,9 +23,32 @@
    #include <gplugin/gplugin-private.h>
    #include <gplugin/gplugin-plugin.h>
    +/**
    + * SECTION:gplugin-core
    + * @Title: Core API
    + * @Short_description: the core api
    + *
    + * This section contains the core api of gplugin, which includes #gplugin_init
    + * and #gplugin_uninit.
    + */
    +
    /******************************************************************************
    * API
    *****************************************************************************/
    +
    +/**
    + * GPLUGIN_DOMAIN: (skip)
    + *
    + * The #GError domain used internally by GPlugin
    + */
    +
    +/**
    + * GPLUGIN_GLOBAL_HEADER_INSIDE: (skip)
    + *
    + * This define is used to determine if we're inside the gplugin global header
    + * file or not.
    + */
    +
    /**
    * gplugin_init:
    *
    --- a/gplugin/gplugin-enums.c.tmpl Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-enums.c.tmpl Sat May 05 19:26:49 2018 -0500
    @@ -22,6 +22,14 @@
    /*** END file-header ***/
    +/**
    + * SECTION:gplugin-enums
    + * @Title: Enumerations
    + * @Short_description: common enumerations
    + *
    + * The enums defined here are used throughout %GPlugin.
    + */
    +
    /*** BEGIN file-production ***/
    /* enumerations from "@filename@" */
    --- a/gplugin/gplugin-loader.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-loader.c Sat May 05 19:26:49 2018 -0500
    @@ -19,6 +19,15 @@
    #include <gplugin/gplugin-core.h>
    +/**
    + * SECTION:gplugin-loader
    + * @Title: Plugin Loader Interface
    + * @Short_description: interface for loading plugins
    + *
    + * A PluginLoader has to implement the interface described here for GPlugin to
    + * be able to use it to load plugins.
    + */
    +
    /******************************************************************************
    * API
    *****************************************************************************/
    @@ -48,7 +57,10 @@
    * gplugin_loader_query_plugin:
    * @loader: #GPluginLoader instance performing the query
    * @filename: filename to query
    - * error: return location for a GError, or NULL
    + * @error: return location for a GError, or NULL
    + *
    + * This function is called by the plugin manager to ask a loader to query the
    + * given file and determine if it's a usable plugin.
    *
    * Return value: (transfer full): A #GPluginPlugin instance or NULL on failure
    */
    @@ -75,7 +87,10 @@
    * gplugin_loader_load_plugin:
    * @loader: #GPluginLoader instance performing the load
    * @plugin: #GPluginPlugin instance to load
    - * error: return location for a GError, or NULL
    + * @error: return location for a GError, or NULL
    + *
    + * This function is called by the plugin manager to ask a loader to load the
    + * given plugin.
    *
    * Return value: TRUE if @plugin was loaded successfully, FALSE otherwise
    */
    @@ -110,6 +125,9 @@
    * @plugin: #GPluginPlugin instance to unload
    * @error: return location for a GError, or NULL
    *
    + * This function is called by the plugin manager to ask a loader to unload the
    + * given plugin.
    + *
    * Return value: TRUE if @plugin was unloaded successfully, FALSE otherwise
    */
    gboolean
    --- a/gplugin/gplugin-manager.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-manager.c Sat May 05 19:26:49 2018 -0500
    @@ -31,6 +31,15 @@
    #include <gplugin/gplugin-file-tree.h>
    +/**
    + * SECTION:gplugin-manager
    + * @Title: Manager API
    + * @Short_description: API for managing plugins
    + *
    + * The manager is used to manager all plugins in %GPlugin. This includes
    + * loading, unloading, querying, checking for new plugins, and so on.
    + */
    +
    /******************************************************************************
    * Enums
    *****************************************************************************/
    --- a/gplugin/gplugin-native-loader.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-native-loader.c Sat May 05 19:26:49 2018 -0500
    @@ -30,6 +30,14 @@
    #define GPLUGIN_LOAD_SYMBOL "gplugin_load"
    #define GPLUGIN_UNLOAD_SYMBOL "gplugin_unload"
    +/**
    + * SECTION:gplugin-native-loader
    + * @Title: Native Loader API
    + * @Short_description: API for the native plugin loader
    + *
    + * Basic API for the native plugin loader.
    + */
    +
    /******************************************************************************
    * Helpers
    *****************************************************************************/
    @@ -289,6 +297,14 @@
    /******************************************************************************
    * API
    *****************************************************************************/
    +
    +/**
    + * GPLUGIN_NATIVE_PLUGIN_ABI_VERSION:
    + *
    + * The ABI version of the #GPluginNativeLoader. Your plugin should use this
    + * as the value for %abi_version when call #gplugin_plugin_info_new.
    + */
    +
    GType
    gplugin_native_loader_get_type(void) {
    static volatile gsize type_volatile = 0;
    --- a/gplugin/gplugin-native-plugin.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-native-plugin.c Sat May 05 19:26:49 2018 -0500
    @@ -26,6 +26,15 @@
    #include <glib/gi18n.h>
    +/**
    + * SECTION:gplugin-native-plugin
    + * @Title: Native Plugin API
    + * @Short_description: API for native plugins
    + *
    + * API for use by native plugins. That is plugins written in a compiled
    + * language.
    + */
    +
    #define GPLUGIN_NATIVE_PLUGIN_GET_PRIVATE(obj) \
    (G_TYPE_INSTANCE_GET_PRIVATE((obj), GPLUGIN_TYPE_NATIVE_PLUGIN, GPluginNativePluginPrivate))
    --- a/gplugin/gplugin-options.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-options.c Sat May 05 19:26:49 2018 -0500
    @@ -23,6 +23,16 @@
    #include <gplugin/gplugin-manager.h>
    +/**
    + * SECTION:gplugin-options
    + * @Title: Command line option support
    + * @Short_description: command line option support
    + *
    + * This section contains #gplugin_get_option_group that makes it easy to
    + * initialize %GPlugin from your application when it is added to a
    + * #GOptionContext.
    + */
    +
    /******************************************************************************
    * Options
    *****************************************************************************/
    --- a/gplugin/gplugin-plugin-info.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-plugin-info.c Sat May 05 19:26:49 2018 -0500
    @@ -21,6 +21,14 @@
    #include <gplugin/gplugin-enums.h>
    #include <gplugin/gplugin-private.h>
    +/**
    + * SECTION:gplugin-plugin-info
    + * @Title: Plugin Info Objects
    + * @Short_description: information about plugins
    + *
    + * #GPluginPluginInfo holds metadata for plugins.
    + */
    +
    #define GPLUGIN_PLUGIN_INFO_GET_PRIVATE(obj) \
    (G_TYPE_INSTANCE_GET_PRIVATE((obj), GPLUGIN_TYPE_PLUGIN_INFO, GPluginPluginInfoPrivate))
    @@ -468,7 +476,7 @@
    * The id of the plugin.
    *
    * While not required, the recommended convention is to use the following
    - * format: <application or library>/<name of the plugin>.
    + * format: &lt;application or library&gt;/&lt;name of the plugin&gt;.
    *
    * For example, the python loader in GPlugin has an id of
    * "gplugin/python-plugin-loader".
    @@ -782,7 +790,9 @@
    * gplugin_plugin_info_get_id:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The id from @info.
    + * Returns the id that the plugin identifies itself as.
    + *
    + * Returns: The id from @info.
    */
    const gchar *
    gplugin_plugin_info_get_id(const GPluginPluginInfo *info) {
    @@ -799,7 +809,10 @@
    * gplugin_plugin_info_get_abi_version:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The abi_version from @info.
    + * Returns the ABI or Application Binary Interface version that the plugin
    + * is supposed to work against.
    + *
    + * Returns: The abi_version from @info.
    */
    guint32
    gplugin_plugin_info_get_abi_version(const GPluginPluginInfo *info) {
    @@ -816,7 +829,11 @@
    * gplugin_plugin_info_get_internal:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: Whether or not this plugin is considered an internal plugin
    + * Returns where or not this plugin is is considered an internal plugin. An
    + * internal plugin would be something like a plugin loader or another plugin
    + * that should not be shown to users.
    + *
    + * Returns: TRUE if the plugin is internal, FALSE otherwise.
    */
    gboolean
    gplugin_plugin_info_get_internal(const GPluginPluginInfo *info) {
    @@ -833,7 +850,12 @@
    * gplugin_plugin_info_get_load_on_query:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: Whether or not this plugin should be loaded when queried
    + * Returns whether or not this plugin should be loaded when queried. This is
    + * useful for internal plugins that are adding functionality and should always
    + * be turned on. The plugin loaders use this to make sure all plugins can
    + * always be loaded.
    + *
    + * Returns: TRUE if the plugin should be loaded on query, FALSE otherwise.
    */
    gboolean
    gplugin_plugin_info_get_load_on_query(const GPluginPluginInfo *info) {
    @@ -850,7 +872,9 @@
    * gplugin_plugin_info_get_name:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The name from @info.
    + * Returns the name of the plugin as specified in @info.
    + *
    + * Returns: The name from @info.
    */
    const gchar *
    gplugin_plugin_info_get_name(const GPluginPluginInfo *info) {
    @@ -867,7 +891,9 @@
    * gplugin_plugin_info_get_version:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The version from @info.
    + * Returns the version of the plugin as specified in @info.
    + *
    + * Returns: The version from @info.
    */
    const gchar *
    gplugin_plugin_info_get_version(const GPluginPluginInfo *info) {
    @@ -884,6 +910,9 @@
    * gplugin_plugin_info_get_version_func: (skip)
    * @info: #GPluginPluginInfo instance
    *
    + * Returns the #GPluginVersionCompareFunc used to compare versions of the
    + * plugin.
    + *
    * Returns: The #GPluginVersionCompareFunc that can compare versions of this
    * plugins.
    */
    @@ -902,7 +931,9 @@
    * gplugin_plugin_info_get_license_id:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The license-id from @info.
    + * Returns the liences id for the plugin as specified in @info.
    + *
    + * Returns: The license-id from @info.
    */
    const gchar *
    gplugin_plugin_info_get_license_id(const GPluginPluginInfo *info) {
    @@ -919,7 +950,9 @@
    * gplugin_plugin_info_get_license_text:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The text of the license from @info.
    + * Returns the license text for the plugin as specified in @info.
    + *
    + * Returns: The text of the license from @info.
    */
    const gchar *
    gplugin_plugin_info_get_license_text(const GPluginPluginInfo *info) {
    @@ -936,7 +969,9 @@
    * gplugin_plugin_info_get_license_url:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The url of the license from @info.
    + * Returns the url of the license for the plugin as specified in @info
    + *
    + * Returns: The url of the license from @info.
    */
    const gchar *
    gplugin_plugin_info_get_license_url(const GPluginPluginInfo *info) {
    @@ -953,7 +988,9 @@
    * gplugin_plugin_info_get_icon:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The icon from @info.
    + * Returns the name of the icon for the plugin as specified in @info.
    + *
    + * Returns: The icon from @info.
    */
    const gchar *
    gplugin_plugin_info_get_icon(const GPluginPluginInfo *info) {
    @@ -970,7 +1007,9 @@
    * gplugin_plugin_info_get_summary:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The summary from @info.
    + * Returns the summery for the plugin as specified in @info.
    + *
    + * Returns: The summary from @info.
    */
    const gchar *
    gplugin_plugin_info_get_summary(const GPluginPluginInfo *info) {
    @@ -987,7 +1026,9 @@
    * gplugin_plugin_info_get_description:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The description from @info.
    + * Returns the description for the plugin as specified in @info.
    + *
    + * Returns: The description from @info.
    */
    const gchar *
    gplugin_plugin_info_get_description(const GPluginPluginInfo *info) {
    @@ -1004,7 +1045,9 @@
    * gplugin_plugin_info_get_category:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The category from @info.
    + * Returns the category of the plugin as specified in @info.
    + *
    + * Returns: The category from @info.
    */
    const gchar *
    gplugin_plugin_info_get_category(const GPluginPluginInfo *info) {
    @@ -1021,8 +1064,9 @@
    * gplugin_plugin_info_get_authors:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: (array zero-terminated=1) (transfer none): The authors from
    - * @info.
    + * Returns the authors of the plugin as specified in @info.
    + *
    + * Returns: (array zero-terminated=1) (transfer none): The authors from @info.
    */
    const gchar * const *
    gplugin_plugin_info_get_authors(const GPluginPluginInfo *info) {
    @@ -1039,7 +1083,9 @@
    * gplugin_plugin_info_get_help:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The help from @info.
    + * Returns the help text for the plugin as specified in @info.
    + *
    + * Returns: The help from @info.
    */
    const gchar *
    gplugin_plugin_info_get_help(const GPluginPluginInfo *info) {
    @@ -1056,7 +1102,9 @@
    * gplugin_plugin_info_get_website:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: The website from @info.
    + * Returns the website for the plugin as specified in @info.
    + *
    + * Returns: The website from @info.
    */
    const gchar *
    gplugin_plugin_info_get_website(const GPluginPluginInfo *info) {
    @@ -1073,8 +1121,10 @@
    * gplugin_plugin_info_get_dependencies:
    * @info: #GPluginPluginInfo instance
    *
    - * Return value: (array zero-terminated=1) (transfer none): The list of
    - * dependencies from @info.
    + * Returns the dependencies of the plugins as specified in @info.
    + *
    + * Returns: (array zero-terminated=1) (transfer none): The list of
    + * dependencies from @info.
    */
    const gchar * const *
    gplugin_plugin_info_get_dependencies(const GPluginPluginInfo *info) {
    @@ -1093,9 +1143,8 @@
    *
    * This function is only used by the native plugin loader.
    *
    - * Return value: TRUE if the plugin has requested to be loaded with it's
    - * symbols bound locally, FALSE if they should bind be bound
    - * globally.
    + * Returns: TRUE if the plugin has requested to be loaded with it's symbols
    + * bound locally, FALSE if they should bind be bound globally.
    */
    gboolean
    gplugin_plugin_info_get_bind_local(const GPluginPluginInfo *info) {
    --- a/gplugin/gplugin-plugin.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-plugin.c Sat May 05 19:26:49 2018 -0500
    @@ -21,6 +21,16 @@
    #include <gplugin/gplugin-marshallers.h>
    #include <gplugin/gplugin-private.h>
    +/**
    + * SECTION:gplugin-plugin
    + * @Title: Plugin Objects
    + * @Short_description: abstract plugin implementation
    + *
    + * #GPluginPlugin is an abstract class that tracks the state of a plugin. It
    + * is subclassed by each loader for them to add additional data for their
    + * implementation.
    + */
    +
    #define GPLUGIN_PLUGIN_GET_PRIVATE(obj) \
    (G_TYPE_INSTANCE_GET_PRIVATE((obj), GPLUGIN_TYPE_PLUGIN, GPluginPluginPrivate))
    @@ -309,7 +319,9 @@
    * gplugin_plugin_get_filename:
    * @plugin: #GPluginPlugin instance
    *
    - * Return value: The filename of @plugin
    + * Returns the filename that @plugin was loaded from.
    + *
    + * Returns: The filename of @plugin
    */
    const gchar *
    gplugin_plugin_get_filename(const GPluginPlugin *plugin) {
    @@ -326,7 +338,9 @@
    * gplugin_plugin_get_loader:
    * @plugin: #GPluginPlugin instance
    *
    - * Return Value: (transfer full): The #GPluginLoader that loaded @plugin
    + * Returns the #GPluginLoader that loaded @plugin.
    + *
    + * Returns: (transfer full): The #GPluginLoader that loaded @plugin
    */
    GPluginLoader *
    gplugin_plugin_get_loader(const GPluginPlugin *plugin) {
    @@ -343,7 +357,9 @@
    * gplugin_plugin_get_info:
    * @plugin: #GPluginPlugin instance
    *
    - * Return value: (transfer full): The #GPluginPluginInfo instance for @plugin
    + * Returns the #GPluginPluginInfo for @plugin.
    + *
    + * Returns: (transfer full): The #GPluginPluginInfo instance for @plugin
    */
    GPluginPluginInfo *
    gplugin_plugin_get_info(const GPluginPlugin *plugin) {
    @@ -362,7 +378,7 @@
    *
    * Gets the current state of @plugin
    *
    - * Return value: (transfer full): The current state of @plugin
    + * Returns: (transfer full): The current state of @plugin
    */
    GPluginPluginState
    gplugin_plugin_get_state(const GPluginPlugin *plugin) {
    @@ -405,8 +421,8 @@
    *
    * Returns a list of plugins that depend on @plugin.
    *
    - * Return value: (element-type GPlugin.Plugin) (transfer none): A #GList of
    - * each plugin that depends on this plugin.
    + * Returns: (element-type GPlugin.Plugin) (transfer none): A #GList of each
    + * plugin that depends on this plugin.
    */
    GList *
    gplugin_plugin_get_dependent_plugins(const GPluginPlugin *plugin) {
    --- a/gplugin/gplugin-plugin.h Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-plugin.h Sat May 05 19:26:49 2018 -0500
    @@ -41,6 +41,8 @@
    GPLUGIN_PLUGIN_STATE_REQUERY,
    GPLUGIN_PLUGIN_STATE_LOADED,
    GPLUGIN_PLUGIN_STATE_LOAD_FAILED,
    +
    + /*< private >*/
    GPLUGIN_PLUGIN_STATES, /*< skip >*/
    } GPluginPluginState;
    --- a/gplugin/gplugin-version.c Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-version.c Sat May 05 19:26:49 2018 -0500
    @@ -15,6 +15,16 @@
    * License along with this library; if not, see <http://www.gnu.org/licenses/>.
    */
    +/**
    + * SECTION:gplugin-version
    + * @Title: Version Information
    + * @Short_description: variables and functions to check the GPlugin version
    + *
    + * GPlugin provides version information, primarily useful in configure
    + * checks for builds that have a configure script. Applications will
    + * not typically use the features described here.
    + */
    +
    #include <gplugin/gplugin-core.h>
    #include <gplugin/gplugin-version.h>
    @@ -105,6 +115,50 @@
    /******************************************************************************
    * GPluginVersion API
    *****************************************************************************/
    +
    +/**
    + * GPLUGIN_MAJOR_VERSION:
    + *
    + * This is the major version number of GPlugin that was compiled against.
    + */
    +
    +/**
    + * GPLUGIN_MINOR_VERSION:
    + *
    + * This is the minor version number of GPlugin that was compiled against.
    + */
    +
    +/**
    + * GPLUGIN_MICRO_VERSION:
    + *
    + * This is the micro version number of GPlugin that was compiled against.
    + */
    +
    +/**
    + * GPLUGIN_EXTRA_VERSION:
    + *
    + * This is the extra version string of GPlugin that was compiled against.
    + */
    +
    +/**
    + * GPLUGIN_VERSION:
    + *
    + * This is the string version number of GPlugin that was compiled against.
    + */
    +
    +/**
    + * GPLUGIN_VERSION_CHECK:
    + * @major: the major version to check for
    + * @minor: the minor version to check for
    + * @micro: the micro version to check for
    + *
    + * Checks the version of the GPlugin library that is being compiled
    + * against. See gplugin_check_version() for a runtime check.
    + *
    + * Returns: %TRUE if the version of the GPlugin header files
    + * is the same as or newer than the passed-in version.
    + */
    +
    /**
    * GPluginVersionCompareFunc:
    * @v1: The first version to compare
    --- a/gplugin/gplugin-version.h.in Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/gplugin-version.h.in Sat May 05 19:26:49 2018 -0500
    @@ -30,10 +30,10 @@
    #define GPLUGIN_VERSION "@GPLUGIN_VERSION@"
    -#define GPLUGIN_VERSION_CHECK(x,y,z) \
    - ((x) == GPLUGIN_MAJOR_VERSION && \
    - ((y) < GPLUGIN_MINOR_VERSION || \
    - ((y) == GPLUGIN_MINOR_VERSION && (z) <= GPLUGIN_MICRO_VERSION)))
    +#define GPLUGIN_VERSION_CHECK(major,minor,micro) \
    + ((major) == GPLUGIN_MAJOR_VERSION && \
    + ((minor) < GPLUGIN_MINOR_VERSION || \
    + ((minor) == GPLUGIN_MINOR_VERSION && (micro) <= GPLUGIN_MICRO_VERSION)))
    #include <glib.h>
    --- a/gplugin/meson.build Sat May 05 17:29:31 2018 -0500
    +++ b/gplugin/meson.build Sat May 05 19:26:49 2018 -0500
    @@ -113,12 +113,16 @@
    output : 'gplugin-version.h',
    configuration : version_conf,
    install : true,
    - install_dir : join_paths(get_option('includedir'), 'gplugin-1.0', 'gplugin'))
    + install_dir : join_paths(get_option('includedir'), 'gplugin-1.0', 'gplugin')
    +)
    +
    GPLUGIN_PUBLIC_BUILT_HEADERS += [
    gplugin_version_h
    ]
    +gplugin_inc = include_directories('.')
    +
    # Build gplugin.h
    GPLUGIN_H_INCLUDES = ''
    @@ -127,6 +131,7 @@
    GPLUGIN_H_INCLUDES,
    header)
    endforeach
    +
    foreach header : ['gplugin-version.h', 'gplugin-enums.h'] # GPLUGIN_PUBLIC_BUILT_HEADERS
    GPLUGIN_H_INCLUDES = '@0@\n#include <gplugin/@1@>'.format(
    GPLUGIN_H_INCLUDES,
    @@ -180,6 +185,7 @@
    version : GPLUGIN_LIBRARY_VERSION,
    install : true
    )
    +
    gplugin_dep = declare_dependency(
    include_directories : [toplevel_inc, include_directories('.')],
    link_with : gplugin,
    @@ -270,3 +276,7 @@
    # subdirectories
    ###############################################################################
    subdir('tests')
    +
    +if ENABLE_DOC
    + subdir('reference')
    +endif
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/gplugin/reference/gplugin-docs.xml Sat May 05 19:26:49 2018 -0500
    @@ -0,0 +1,65 @@
    +<?xml version="1.0"?>
    +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
    +
    +<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
    +<!ENTITY version SYSTEM "version.xml">
    +]>
    +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
    + <bookinfo>
    + <title>GPlugin Reference Manual</title>
    + <abstract>
    + <title>GPlugin &version;</title>
    + <para>
    + GPlugin is a GObject based library that implements a reusable plugin system that
    + supports loading plugins in other languages
    + via loaders. GPlugin also implements
    + dependencies among the plugins.
    + </para>
    + </abstract>
    + </bookinfo>
    +
    + <part id="object-hierarchy">
    + <title>Object Hierarchy</title>
    +
    + <xi:include href="xml/tree_index.sgml"/>
    + </part>
    +
    + <part id="API">
    + <title>API Reference</title>
    +
    + <chapter id="coreapi">
    + <title>Core API</title>
    + <xi:include href="xml/gplugin-core.xml"/>
    + <xi:include href="xml/gplugin-loader.xml"/>
    + <xi:include href="xml/gplugin-manager.xml"/>
    + <xi:include href="xml/gplugin-options.xml"/>
    + <xi:include href="xml/gplugin-plugin-info.xml"/>
    + <xi:include href="xml/gplugin-plugin.xml"/>
    + <xi:include href="xml/gplugin-version.xml"/>
    + </chapter>
    +
    + <chapter id="nativeapi">
    + <title>Native API</title>
    +
    + <xi:include href="xml/gplugin-native.xml"/>
    + <xi:include href="xml/gplugin-native-plugin.xml"/>
    + <xi:include href="xml/gplugin-native-loader.xml"/>
    + </chapter>
    + </part>
    +
    + <index id="api-index-full">
    + <title>Index</title>
    + <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
    + </index>
    + <index id="api-index-deprecated" role="deprecated">
    + <title>Index of deprecated symbols</title>
    + <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
    + </index>
    +<!-- <index id="api-index-2.11.0" role="2.11.0">
    + <title>Index of new symbols in 2.11.0</title>
    + <xi:include href="xml/api-index-2.11.0.xml"><xi:fallback /></xi:include>
    + </index>
    + -->
    + <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
    +</book>
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/gplugin/reference/meson.build Sat May 05 19:26:49 2018 -0500
    @@ -0,0 +1,43 @@
    +DOC_MODULE = 'gplugin'
    +
    +# Header files or dirs to ignore when scanning. Use base file/dir names
    +ignore_hfiles = [
    + 'gplugin-private.h',
    + 'gplugin-loader-tests.h',
    + 'gplugin-marshallers.h',
    + 'gplugin-native-private.h',
    + 'dynamic-test.h',
    +]
    +ignore_hfiles += GPLUGIN_PRIVATE_HEADERS
    +
    +# Extra options to supply to gtkdoc-scan.
    +scan_args = [
    + '--deprecated-guards=GPLUGIN_DISABLE_DEPRECATED',
    + '--rebuild-types',
    + '--rebuild-sections',
    + '--ignore-headers=' + ' '.join(ignore_hfiles),
    +]
    +
    +# Extra options to supply to gtkdoc-mkdb.
    +mkdb_args = [
    + '--ignore-files=' + ' '.join(ignore_hfiles),
    +]
    +
    +gplugin_version_xml = configure_file(
    + input : 'version.xml.in',
    + output : 'version.xml',
    + configuration : version_conf)
    +
    +content_files = [
    +]
    +
    +gnome.gtkdoc(DOC_MODULE,
    + main_xml : DOC_MODULE + '-docs.xml',
    + src_dir : gplugin_inc,
    + dependencies : gplugin_dep,
    + install : true,
    + scan_args : scan_args,
    + mkdb_args : mkdb_args,
    + gobject_typesfile : DOC_MODULE + '.types',
    + content_files : content_files,
    +)
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/gplugin/reference/version.xml.in Sat May 05 19:26:49 2018 -0500
    @@ -0,0 +1,1 @@
    +@GPLUGIN_VERSION@
    --- a/meson.build Sat May 05 17:29:31 2018 -0500
    +++ b/meson.build Sat May 05 19:26:49 2018 -0500
    @@ -93,6 +93,20 @@
    toplevel_inc = include_directories('.')
    +
    +###############################################################################
    +# gtk-doc
    +###############################################################################
    +ENABLE_DOC = get_option('doc')
    +if ENABLE_DOC
    + if meson.version().version_compare('<0.41.2')
    + if force_deps
    + error('Meson 0.41.2 or newer is required to build documentation.')
    + endif
    + ENABLE_DOC = false
    + endif
    +endif
    +
    ###############################################################################
    # Subdirectories
    ###############################################################################
    --- a/meson_options.txt Sat May 05 17:29:31 2018 -0500
    +++ b/meson_options.txt Sat May 05 19:26:49 2018 -0500
    @@ -20,9 +20,15 @@
    )
    option(
    - 'gtk3',
    + 'doc',
    type : 'boolean', value : true,
    - description : 'Whether or not to build the gtk3 library'
    + description : 'build documentation with gtk-doc'
    +)
    +
    +option(
    + 'gtk3',
    + type : 'boolean', value : true,
    + description : 'Whether or not to build the gtk3 library'
    )
    option(