From cb1172ee3d929dddb3313fd4611160fa8cd5b3e6 Mon Sep 17 00:00:00 2001
From: Lubomir Rintel <lkundrak@v3.sk>
Date: Tue, 26 Jun 2018 12:02:33 +0200
Subject: [PATCH] docs: include missing documentation in libnm and D-Bus docs

Check that we don't repeat the omission in future.
---
 Makefile.am                       |  6 ++++++
 docs/api/Makefile.am              |  1 -
 docs/api/network-manager-docs.xml | 22 ++++++++++++++++++-
 docs/libnm/libnm-docs.xml         | 36 ++++++++++++++++++++++++++-----
 docs/meson.build                  |  6 ++++++
 tools/check-docs.sh               | 22 +++++++++++++++++++
 6 files changed, 86 insertions(+), 7 deletions(-)
 create mode 100755 tools/check-docs.sh

diff --git a/Makefile.am b/Makefile.am
index 4974a33182..53235df7e1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -390,6 +390,11 @@ EXTRA_DIST += \
 	$(dbusinterfaces_DATA) \
 	introspection/meson.build
 
+check-docs:
+	$(srcdir)/tools/check-docs.sh "$(srcdir)"
+
+check_local += check-docs
+
 ###############################################################################
 
 libnm_core_lib_h_pub_real = \
@@ -4840,6 +4845,7 @@ EXTRA_DIST += \
 	shared/nm-version-macros.h.in \
 	shared/meson.build \
 	\
+	tools/check-docs.sh \
 	tools/check-exports.sh \
 	tools/create-exports-NetworkManager.sh \
 	tools/debug-helper.py \
diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am
index 39a23b6a95..03b9ce065a 100644
--- a/docs/api/Makefile.am
+++ b/docs/api/Makefile.am
@@ -62,7 +62,6 @@ content_files = \
 	dbus-org.freedesktop.NetworkManager.Device.Vlan.xml \
 	dbus-org.freedesktop.NetworkManager.Device.Adsl.xml \
 	dbus-org.freedesktop.NetworkManager.AgentManager.xml \
-	dbus-org.freedesktop.NetworkManager.Device.WiMax.xml \
 	dbus-org.freedesktop.NetworkManager.Device.IPTunnel.xml \
 	dbus-org.freedesktop.NetworkManager.Device.Tun.xml \
 	dbus-org.freedesktop.NetworkManager.Device.Bridge.xml \
diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml
index 0521700c72..790cfb572a 100644
--- a/docs/api/network-manager-docs.xml
+++ b/docs/api/network-manager-docs.xml
@@ -189,17 +189,22 @@
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Generic.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Infiniband.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.IPTunnel.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Lowpan.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macsec.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Macvlan.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Modem.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OlpcMesh.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OvsBridge.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OvsInterface.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.OvsPort.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Ppp.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Team.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Tun.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Veth.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vlan.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Vxlan.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wireless.xml"/>
-      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.WiMax.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.Wpan.xml"/>
       <xi:include href="dbus-org.freedesktop.NetworkManager.PPP.xml"/>
     </chapter>
 
@@ -240,10 +245,25 @@
       <xi:include href="dbus-org.freedesktop.NetworkManager.AccessPoint.xml"/>
     </chapter>
 
+    <chapter id="ref-dbus-checkpoint">
+      <title>The <literal>/org/freedesktop/NetworkManager/Checkpoint/*</literal> objects</title>
+      <!-- TODO: Describe the objects here -->
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Checkpoint.xml"/>
+    </chapter>
+
     <chapter id="dbus-types">
       <title>Types</title>
       <xi:include href="../../libnm-core/nm-dbus-types.xml"/>
     </chapter>
+
+    <!--
+      These are obsolete and intentionally ommitted from the manual since they can't
+      appear on the D-Bus API of the present version of NetworkManager.
+      Keep them here so that "make check" won't think that they were skipped accidentally .
+      <xi:include href="dbus-org.freedesktop.NetworkManager.Device.WiMax.xml"/>
+      <xi:include href="dbus-org.freedesktop.NetworkManager.WiMax.Nsp.xml"/>
+    -->
+
   </part>
 
   <part id="secret-agents">
diff --git a/docs/libnm/libnm-docs.xml b/docs/libnm/libnm-docs.xml
index 73098518fe..e76f7bb0f3 100644
--- a/docs/libnm/libnm-docs.xml
+++ b/docs/libnm/libnm-docs.xml
@@ -191,12 +191,13 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
     <xi:include href="xml/nm-setting.xml"/>
     <xi:include href="xml/nm-setting-connection.xml"/>
     <!-- begin alphabetical -->
+    <xi:include href="xml/nm-setting-6lowpan.xml"/>
     <xi:include href="xml/nm-setting-8021x.xml"/>
     <xi:include href="xml/nm-setting-adsl.xml"/>
     <xi:include href="xml/nm-setting-bluetooth.xml"/>
     <xi:include href="xml/nm-setting-bond.xml"/>
-    <xi:include href="xml/nm-setting-bridge.xml"/>
     <xi:include href="xml/nm-setting-bridge-port.xml"/>
+    <xi:include href="xml/nm-setting-bridge.xml"/>
     <xi:include href="xml/nm-setting-cdma.xml"/>
     <xi:include href="xml/nm-setting-dcb.xml"/>
     <xi:include href="xml/nm-setting-dummy.xml"/>
@@ -210,19 +211,27 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
     <xi:include href="xml/nm-setting-macsec.xml"/>
     <xi:include href="xml/nm-setting-macvlan.xml"/>
     <xi:include href="xml/nm-setting-olpc-mesh.xml"/>
-    <xi:include href="xml/nm-setting-ppp.xml"/>
+    <xi:include href="xml/nm-setting-ovs-bridge.xml"/>
+    <xi:include href="xml/nm-setting-ovs-interface.xml"/>
+    <xi:include href="xml/nm-setting-ovs-patch.xml"/>
+    <xi:include href="xml/nm-setting-ovs-port.xml"/>
     <xi:include href="xml/nm-setting-pppoe.xml"/>
+    <xi:include href="xml/nm-setting-ppp.xml"/>
+    <xi:include href="xml/nm-setting-proxy.xml"/>
     <xi:include href="xml/nm-setting-serial.xml"/>
-    <xi:include href="xml/nm-setting-team.xml"/>
+    <xi:include href="xml/nm-setting-tc-config.xml"/>
     <xi:include href="xml/nm-setting-team-port.xml"/>
+    <xi:include href="xml/nm-setting-team.xml"/>
     <xi:include href="xml/nm-setting-tun.xml"/>
+    <xi:include href="xml/nm-setting-user.xml"/>
     <xi:include href="xml/nm-setting-vlan.xml"/>
     <xi:include href="xml/nm-setting-vpn.xml"/>
     <xi:include href="xml/nm-setting-vxlan.xml"/>
     <xi:include href="xml/nm-setting-wimax.xml"/>
     <xi:include href="xml/nm-setting-wired.xml"/>
-    <xi:include href="xml/nm-setting-wireless.xml"/>
     <xi:include href="xml/nm-setting-wireless-security.xml"/>
+    <xi:include href="xml/nm-setting-wireless.xml"/>
+    <xi:include href="xml/nm-setting-wpan.xml"/>
     <!-- end alphabetical -->
   </chapter>
 
@@ -230,6 +239,7 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
     <title>Device and Runtime Configuration API Reference</title>
     <xi:include href="xml/nm-device.xml"/>
     <!-- begin alphabetical -->
+    <xi:include href="xml/nm-device-6lowpan.xml"/>
     <xi:include href="xml/nm-device-adsl.xml"/>
     <xi:include href="xml/nm-device-bond.xml"/>
     <xi:include href="xml/nm-device-bridge.xml"/>
@@ -243,12 +253,17 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
     <xi:include href="xml/nm-device-macvlan.xml"/>
     <xi:include href="xml/nm-device-modem.xml"/>
     <xi:include href="xml/nm-device-olpc-mesh.xml"/>
+    <xi:include href="xml/nm-device-ovs-bridge.xml"/>
+    <xi:include href="xml/nm-device-ovs-interface.xml"/>
+    <xi:include href="xml/nm-device-ovs-port.xml"/>
+    <xi:include href="xml/nm-device-ppp.xml"/>
     <xi:include href="xml/nm-device-team.xml"/>
     <xi:include href="xml/nm-device-tun.xml"/>
     <xi:include href="xml/nm-device-vlan.xml"/>
     <xi:include href="xml/nm-device-vxlan.xml"/>
     <xi:include href="xml/nm-device-wifi.xml"/>
     <xi:include href="xml/nm-device-wimax.xml"/>
+    <xi:include href="xml/nm-device-wpan.xml"/>
     <!-- end alphabetical -->
     <xi:include href="xml/nm-active-connection.xml"/>
     <xi:include href="xml/nm-vpn-connection.xml"/>
@@ -257,6 +272,7 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
     <xi:include href="xml/nm-wimax-nsp.xml"/>
     <xi:include href="xml/nm-ip-config.xml"/>
     <xi:include href="xml/nm-dhcp-config.xml"/>
+    <xi:include href="xml/nm-checkpoint.xml"/>
   </chapter>
 
   <chapter>
@@ -267,10 +283,20 @@ print ("NetworkManager version " + client.get_version())]]></programlisting></in
 
   <chapter>
     <title>VPN Plugin API Reference</title>
-    <xi:include href="xml/nm-vpn-dbus-interface.xml"/>
+    <xi:include href="xml/nm-vpn-service-plugin.xml"/>
+    <xi:include href="xml/nm-vpn-plugin-info.xml"/>
+    <xi:include href="xml/nm-vpn-editor.xml"/>
     <xi:include href="xml/nm-vpn-editor-plugin.xml"/>
+    <xi:include href="xml/nm-vpn-plugin-old.xml"/>
   </chapter>
 
+  <!--
+    These don't contain any useful documentaiton. Keep them here,
+    so that tools/check-docs.sh knows that we did omit them intentionally.
+    <xi:include href="xml/nm-core-enum-types.xml"/>
+    <xi:include href="xml/nm-enum-types.xml"/>
+  -->
+
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
diff --git a/docs/meson.build b/docs/meson.build
index 78ace8b297..1fb21fb47d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -10,3 +10,9 @@ if enable_libnm_glib
   subdir('libnm-util')
   subdir('libnm-glib')
 endif
+
+test(
+  'check-docs',
+  find_program(join_paths(meson.source_root(), 'tools', 'check-docs.sh')),
+  args: [meson.source_root()]
+)
diff --git a/tools/check-docs.sh b/tools/check-docs.sh
new file mode 100755
index 0000000000..9dcdb1ef3b
--- /dev/null
+++ b/tools/check-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+
+SOURCEDIR=$1
+[ -n "$SOURCEDIR" ] && SOURCEDIR="$SOURCEDIR/"
+
+# Check that the D-Bus API docs contain all known interfaces
+if (sed -n 's/.*<xi:include href="dbus-\(.*\.xml\)".*/\1\n\1/p' $SOURCEDIR''docs/api/network-manager-docs.xml;
+    cd $SOURCEDIR''introspection; ls *.xml) |sort |uniq -u| grep . >&2; then
+	echo "*** Error: D-Bus interfaces not included in docs/api/network-manager-docs.xml ***" >&2
+	exit 1
+fi
+
+# Check that files that define types that are in public libnm API are included in libnm documentation.
+# Don't complain about readability or I'll rewrite this in Perl.
+if (sed -n 's/.*<xi:include href="\(xml\/.*\.xml\)".*/\1\n\1/p' $SOURCEDIR''docs/libnm/libnm-docs.xml;
+    grep -lE "$(sed -n 's/^[\t ]*\(.*_get_type\);/\1/p' $SOURCEDIR''libnm/libnm.ver |xargs echo |sed 's/ /|/g')" $SOURCEDIR''libnm{,-core}/*.h |
+    sed 's,.*/,xml/,;s/\.h$/.xml/') |sort |uniq -u| grep . >&2; then
+	echo "*** Error: libnm classes not included in docs/libnm/libnm-docs.xml ***" >&2
+	exit 1
+fi
+
+exit 0