merge: branch 'lr/gtk-doc'

17 files changed, 158 insertions, 47 deletions

diff --git a/.gitignore b/.gitignore
index 73c47352..611dc9e1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,3 +72,20 @@ man/*.1
 /test-driver
 **/tests/test-*.log
 **/tests/test-*.trs
+
+xml/
+html/
+gtk-doc.make
+libnma-decl-list.txt
+libnma-decl.txt
+libnma-overrides.txt
+libnma-sections.txt
+libnma-undeclared.txt
+libnma-undocumented.txt
+libnma-unused.txt
+libnma.args
+libnma.hierarchy
+libnma.interfaces
+libnma.prerequisites
+libnma.signals
+libnma.types
diff --git a/Makefile.am b/Makefile.am
index cba532f6..a57e15f0 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,5 +1,6 @@
 include $(GLIB_MAKEFILE)
 -include $(INTROSPECTION_MAKEFILE)
+include $(top_srcdir)/gtk-doc.make
 
 ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
 
@@ -23,10 +24,6 @@ check_local =
 
 TESTS =
 
-EXTRA_DIST =
-
-CLEANFILES =
-
 DISTCLEANFILES =
 
 DISTCHECK_CONFIGURE_FLAGS = \
@@ -832,6 +829,32 @@ man_MANS += \
 
 ###############################################################################
 
+DOC_MODULE = libnma
+
+DOC_SOURCE_DIR = $(top_srcdir)/src/libnma
+
+SCAN_OPTIONS=--rebuild-types --rebuild-sections
+
+DOC_MAIN_SGML_FILE = libnma-docs.xml
+
+GTKDOC_LIBS = src/libnma/libnma.la
+
+scan-build.stamp: $(GTKDOC_LIBS)
+
+HFILE_GLOB = $(top_srcdir)/src/libnma/*.h
+
+CFILE_GLOB = $(top_srcdir)/src/libnma/*.c
+
+IGNORE_HFILES = \
+	nma-resources.h
+
+mkdb_ignore_c_files = \
+	nma-resources.c
+
+MKDB_OPTIONS = --ignore-files "$(IGNORE_HFILES) $(mkdb_ignore_c_files)"
+
+###############################################################################
+
 check_PROGRAMS += $(check_programs)
 
 check-local: $(check_local)
diff --git a/autogen.sh b/autogen.sh
index 53705a15..d783df06 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -14,6 +14,7 @@ PKG_NAME=nm-applet
 }
 
 (cd $srcdir;
+    gtkdocize &&
     autoreconf --install --symlink &&
     intltoolize --force &&
     autoreconf
diff --git a/configure.ac b/configure.ac
index 3e4a3dd3..dc6fdc2c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -71,6 +71,11 @@ else
     AC_DEFINE_UNQUOTED([ISO_CODES_PREFIX],["$prefix"],[ISO codes prefix])
 fi
 
+dnl
+dnl API documentation
+dnl
+GTK_DOC_CHECK(1.0)
+
 AC_ARG_WITH(libnm-gtk, AS_HELP_STRING([--without-libnm-gtk], [dont build legacy library libnm-gtk which depends on libnm-glib/libnm-util/dbus-glib]))
 if test "$with_libnm_gtk" != no; then
 	PKG_CHECK_MODULES(LIBNM_GLIB,
diff --git a/libnma-docs.xml b/libnma-docs.xml
new file mode 100644
index 00000000..0ef92e1c
--- /dev/null
+++ b/libnma-docs.xml
@@ -0,0 +1,71 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
+]>
+<book id="index">
+  <bookinfo>
+    <title>libnma Reference Manual</title>
+    <releaseinfo>
+      for libnma &package_version;.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="https://developer.gnome.org/libnma/index.html">https://developer.gnome.org/libnma/</ulink>.
+    </releaseinfo>
+
+    <copyright>
+ ]    <year>2017</year>
+      <holder>The &package_tarname; Authors</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this
+        document under the terms of the <citetitle>GNU Free
+        Documentation License</citetitle>, Version 1.1 or any later
+        version published by the Free Software Foundation with no
+        Invariant Sections, no Front-Cover Texts, and no Back-Cover
+        Texts. You may obtain a copy of the <citetitle>GNU Free
+        Documentation License</citetitle> from the Free Software
+        Foundation by visiting <ulink type="http"
+        url="http://www.fsf.org">their Web site</ulink> or by writing
+        to:
+
+        <address>
+          The Free Software Foundation, Inc.,
+          <street>51 Franklin Street</street> - Fifth Floor,
+          <city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode>,
+          <country>USA</country>
+        </address>
+      </para>
+    </legalnotice>
+  </bookinfo>
+
+  <chapter id="api-reference">
+    <title>libnma API reference</title>
+    <xi:include href="xml/nma-ui-utils.xml"/>
+    <xi:include href="xml/nma-mobile-wizard.xml"/>
+    <xi:include href="xml/nma-mobile-providers.xml"/>
+    <xi:include href="xml/nma-vpn-password-dialog.xml"/>
+    <xi:include href="xml/nma-wifi-dialog.xml"/>
+  </chapter>
+
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+    <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
diff --git a/src/libnm-gtk/nm-mobile-providers.c b/src/libnm-gtk/nm-mobile-providers.c
index 996d61a7..a6c06007 100644
--- a/src/libnm-gtk/nm-mobile-providers.c
+++ b/src/libnm-gtk/nm-mobile-providers.c
@@ -1134,7 +1134,7 @@ struct _NMAMobileProvidersDatabasePrivate {
  * @self: a #NMAMobileProvidersDatabase.
  *
  * Returns: (element-type utf8 NMGtk.CountryInfo) (transfer none): a
- *	 hash table where keys are country names #gchar and values are #NMACountryInfos.
+ *	 hash table where keys are country names #gchar and values are #NMACountryInfo.
  */
 GHashTable *
 nma_mobile_providers_database_get_countries (NMAMobileProvidersDatabase *self)
diff --git a/src/libnm-gtk/nm-mobile-providers.h b/src/libnm-gtk/nm-mobile-providers.h
index 4442d7fb..d0149850 100644
--- a/src/libnm-gtk/nm-mobile-providers.h
+++ b/src/libnm-gtk/nm-mobile-providers.h
@@ -22,10 +22,6 @@
  * Copyright (C) 2012 Lanedo GmbH.
  */
 
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef NM_MOBILE_PROVIDERS_H
 #define NM_MOBILE_PROVIDERS_H
 
diff --git a/src/libnm-gtk/nm-mobile-wizard.h b/src/libnm-gtk/nm-mobile-wizard.h
index 5f626f67..21c7e48f 100644
--- a/src/libnm-gtk/nm-mobile-wizard.h
+++ b/src/libnm-gtk/nm-mobile-wizard.h
@@ -20,10 +20,6 @@
  * (C) Copyright 2008 - 2011 Red Hat, Inc.
  */
 
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef MOBILE_WIZARD_H
 #define MOBILE_WIZARD_H
 
diff --git a/src/libnm-gtk/nm-ui-utils.h b/src/libnm-gtk/nm-ui-utils.h
index 5ae50afd..09d04627 100644
--- a/src/libnm-gtk/nm-ui-utils.h
+++ b/src/libnm-gtk/nm-ui-utils.h
@@ -17,11 +17,6 @@
  * (C) Copyright 2007 - 2015 Red Hat, Inc.
  */
 
-
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef NMA_UI_UTILS_H
 #define NMA_UI_UTILS_H
 
diff --git a/src/libnm-gtk/nm-wifi-dialog.h b/src/libnm-gtk/nm-wifi-dialog.h
index eb837c20..81843230 100644
--- a/src/libnm-gtk/nm-wifi-dialog.h
+++ b/src/libnm-gtk/nm-wifi-dialog.h
@@ -19,11 +19,6 @@
  * (C) Copyright 2007 - 2012 Red Hat, Inc.
  */
 
-
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef NMA_WIFI_DIALOG_H
 #define NMA_WIFI_DIALOG_H
 
diff --git a/src/libnm-gtk/nm-wireless-dialog.h b/src/libnm-gtk/nm-wireless-dialog.h
index 7c481663..00d6cbb8 100644
--- a/src/libnm-gtk/nm-wireless-dialog.h
+++ b/src/libnm-gtk/nm-wireless-dialog.h
@@ -19,11 +19,6 @@
  * (C) Copyright 2007 - 2012 Red Hat, Inc.
  */
 
-
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef NMA_WIRELESS_DIALOG_H
 #define NMA_WIRELESS_DIALOG_H
 
diff --git a/src/libnma/nma-mobile-providers.c b/src/libnma/nma-mobile-providers.c
index d6b44fd5..7d115d07 100644
--- a/src/libnma/nma-mobile-providers.c
+++ b/src/libnma/nma-mobile-providers.c
@@ -111,6 +111,7 @@ nma_mobile_access_method_unref (NMAMobileAccessMethod *method)
 
 /**
  * nma_mobile_access_method_get_name:
+ * @method: a #NMAMobileAccessMethod
  *
  * Returns: (transfer none): the name of the method.
  */
@@ -124,6 +125,7 @@ nma_mobile_access_method_get_name (NMAMobileAccessMethod *method)
 
 /**
  * nma_mobile_access_method_get_username:
+ * @method: a #NMAMobileAccessMethod
  *
  * Returns: (transfer none): the username.
  */
@@ -137,6 +139,7 @@ nma_mobile_access_method_get_username (NMAMobileAccessMethod *method)
 
 /**
  * nma_mobile_access_method_get_password:
+ * @method: a #NMAMobileAccessMethod
  *
  * Returns: (transfer none): the password.
  */
@@ -150,6 +153,7 @@ nma_mobile_access_method_get_password (NMAMobileAccessMethod *method)
 
 /**
  * nma_mobile_access_method_get_gateway:
+ * @method: a #NMAMobileAccessMethod
  *
  * Returns: (transfer none): the gateway.
  */
@@ -163,6 +167,7 @@ nma_mobile_access_method_get_gateway (NMAMobileAccessMethod *method)
 
 /**
  * nma_mobile_access_method_get_dns:
+ * @method: a #NMAMobileAccessMethod
  *
  * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): the list of DNS.
  */
@@ -176,6 +181,7 @@ nma_mobile_access_method_get_dns (NMAMobileAccessMethod *method)
 
 /**
  * nma_mobile_access_method_get_3gpp_apn:
+ * @method: a #NMAMobileAccessMethod
  *
  * Returns: (transfer none): the 3GPP APN.
  */
@@ -189,6 +195,7 @@ nma_mobile_access_method_get_3gpp_apn (NMAMobileAccessMethod *method)
 
 /**
  * nma_mobile_access_method_get_family:
+ * @method: a #NMAMobileAccessMethod
  *
  * Returns: a #NMAMobileFamily.
  */
@@ -268,6 +275,7 @@ nma_mobile_provider_unref (NMAMobileProvider *provider)
 
 /**
  * nma_mobile_provider_get_name:
+ * @provider: a #NMAMobileProvider
  *
  * Returns: (transfer none): the name of the provider.
  */
@@ -378,6 +386,7 @@ nma_country_info_unref (NMACountryInfo *country_info)
 
 /**
  * nma_country_info_get_country_code:
+ * @country_info: a #NMACountryInfo
  *
  * Returns: (transfer none): the code of the country.
  */
@@ -391,6 +400,7 @@ nma_country_info_get_country_code (NMACountryInfo *country_info)
 
 /**
  * nma_country_info_get_country_name:
+ * @country_info: a #NMACountryInfo
  *
  * Returns: (transfer none): the name of the country.
  */
@@ -404,6 +414,7 @@ nma_country_info_get_country_name (NMACountryInfo *country_info)
 
 /**
  * nma_country_info_get_providers:
+ * @country_info: a #NMACountryInfo
  *
  * Returns: (element-type NMAMobileProvider) (transfer none): the
  *	 list of #NMAMobileProvider this country exposes.
@@ -1134,7 +1145,7 @@ struct _NMAMobileProvidersDatabasePrivate {
  * @self: a #NMAMobileProvidersDatabase.
  *
  * Returns: (element-type utf8 NMACountryInfo) (transfer none): a
- *	 hash table where keys are country names #gchar and values are #NMACountryInfos.
+ *	 hash table where keys are country names #gchar and values are #NMACountryInfo.
  */
 GHashTable *
 nma_mobile_providers_database_get_countries (NMAMobileProvidersDatabase *self)
diff --git a/src/libnma/nma-mobile-providers.h b/src/libnma/nma-mobile-providers.h
index 4442d7fb..5074e329 100644
--- a/src/libnma/nma-mobile-providers.h
+++ b/src/libnma/nma-mobile-providers.h
@@ -22,10 +22,6 @@
  * Copyright (C) 2012 Lanedo GmbH.
  */
 
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef NM_MOBILE_PROVIDERS_H
 #define NM_MOBILE_PROVIDERS_H
 
@@ -36,6 +32,12 @@
 /******************************************************************************/
 /* Access method type */
 
+/**
+ * NMAMobileFamily:
+ * @NMA_MOBILE_FAMILY_UNKNOWN: Unknown or invalid network access method
+ * @NMA_MOBILE_FAMILY_3GPP: 3rd Generation Partnership Project (3GPP) network
+ * @NMA_MOBILE_FAMILY_CDMA: A CDMA network
+ */
 typedef enum {
     NMA_MOBILE_FAMILY_UNKNOWN = 0,
     NMA_MOBILE_FAMILY_3GPP,
diff --git a/src/libnma/nma-mobile-wizard.c b/src/libnma/nma-mobile-wizard.c
index a035c8d4..f103c24b 100644
--- a/src/libnma/nma-mobile-wizard.c
+++ b/src/libnma/nma-mobile-wizard.c
@@ -1565,7 +1565,14 @@ get_country_from_locale (void)
 
 /**
  * nma_mobile_wizard_new: (skip)
+ * @parent:
+ * @window_group:
+ * @modem_caps:
+ * @will_connect_after:
  * @cb: (scope async):
+ * @user_data:
+ *
+ * Returns: the newly created #NMAMobileWizard
  */
 NMAMobileWizard *
 nma_mobile_wizard_new (GtkWindow *parent,
diff --git a/src/libnma/nma-mobile-wizard.h b/src/libnma/nma-mobile-wizard.h
index 5f626f67..a63221c7 100644
--- a/src/libnma/nma-mobile-wizard.h
+++ b/src/libnma/nma-mobile-wizard.h
@@ -20,10 +20,6 @@
  * (C) Copyright 2008 - 2011 Red Hat, Inc.
  */
 
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef MOBILE_WIZARD_H
 #define MOBILE_WIZARD_H
 
@@ -33,6 +29,17 @@
 
 typedef struct NMAMobileWizard NMAMobileWizard;
 
+/**
+ * NMAMobileWizardAccessMethod:
+ * @provider_name: The mobile network provider name
+ * @plan_name: The provided network access billing plan
+ * @devtype: Required NetworkManager device capabilities
+ * @username: User login
+ * @password: User secret
+ * @gsm_apn: The GSM Access Point Name
+ *
+ * Network access method details.
+ */
 typedef struct {
 	char *provider_name;
 	char *plan_name;
diff --git a/src/libnma/nma-ui-utils.h b/src/libnma/nma-ui-utils.h
index 46fc44a4..8cedfecc 100644
--- a/src/libnma/nma-ui-utils.h
+++ b/src/libnma/nma-ui-utils.h
@@ -17,11 +17,6 @@
  * Copyright 2015 Red Hat, Inc.
  */
 
-
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef NMA_UI_UTILS_H
 #define NMA_UI_UTILS_H
 
diff --git a/src/libnma/nma-wifi-dialog.h b/src/libnma/nma-wifi-dialog.h
index 6f02bfc5..4c6addd3 100644
--- a/src/libnma/nma-wifi-dialog.h
+++ b/src/libnma/nma-wifi-dialog.h
@@ -19,11 +19,6 @@
  * Copyright 2007 - 2014 Red Hat, Inc.
  */
 
-
-/* WARNING: this file is private API between nm-applet and various GNOME
- * bits; it may change without notice and is not guaranteed to be stable.
- */
-
 #ifndef NMA_WIFI_DIALOG_H
 #define NMA_WIFI_DIALOG_H