diff options
author | Lubomir Rintel <lkundrak@v3.sk> | 2016-04-21 18:06:43 +0200 |
---|---|---|
committer | Lubomir Rintel <lkundrak@v3.sk> | 2016-04-22 10:02:37 +0200 |
commit | db6ebe003dd8f96b18824809c3fcecd1390788e5 (patch) | |
tree | d33120ebd17c24b2aa9afb8417094858a697b00e | |
parent | c850868fafaaa893d00718620e2e49b2fe18406c (diff) | |
download | NetworkManager-db6ebe003dd8f96b18824809c3fcecd1390788e5.tar.gz |
docs: include the D-Bus enums reference with the API documentation
Otherwise the types links would be dangling or resolved to slightly
irrelevant documentation in libnm or completely irrelevant documentation
in libnm-util.
-rw-r--r-- | .gitignore | 2 | ||||
-rw-r--r-- | docs/api/Makefile.am | 2 | ||||
-rw-r--r-- | docs/api/network-manager-docs.xml | 5 | ||||
-rw-r--r-- | libnm-core/Makefile.am | 8 | ||||
-rwxr-xr-x | tools/enums-to-docbook.pl | 198 |
5 files changed, 214 insertions, 1 deletions
diff --git a/.gitignore b/.gitignore index 00210f4203..d491e3343e 100644 --- a/.gitignore +++ b/.gitignore @@ -154,6 +154,8 @@ test-*.trs /libnm-core/tests/test-setting-8021x /libnm-core/tests/test-setting-bond /libnm-core/tests/test-setting-dcb +/libnm-core/nm-dbus-types.xml +/libnm-core/nm-vpn-dbus-types.xml /libnm-glib/nm-secret-agent-glue.h /libnm-glib/nm-vpn-plugin-glue.h diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index aeba9d29b0..5aafc26248 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -73,6 +73,8 @@ content_files = \ $(top_builddir)/introspection/nmdbus-settings-org.freedesktop.NetworkManager.Settings.xml \ $(top_builddir)/introspection/nmdbus-device-ethernet-org.freedesktop.NetworkManager.Device.Wired.xml \ $(top_builddir)/introspection/nmdbus-ip4-config-org.freedesktop.NetworkManager.IP4Config.xml \ + $(top_builddir)/libnm-core/nm-dbus-types.xml \ + $(top_builddir)/libnm-core/nm-vpn-dbus-types.xml \ $(top_builddir)/man/nmcli.xml \ $(top_builddir)/man/nmtui.xml \ $(top_builddir)/man/nm-online.xml \ diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index ff1cb82d00..722e33fd19 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -99,6 +99,11 @@ <xi:include href="../../introspection/nmdbus-vpn-plugin-org.freedesktop.NetworkManager.VPN.Plugin.xml"/> <xi:include href="../../introspection/nmdbus-secret-agent-org.freedesktop.NetworkManager.SecretAgent.xml"/> </section> + <section id="dbus-types"> + <title>Types</title> + <xi:include href="../../libnm-core/nm-dbus-types.xml"/> + <xi:include href="../../libnm-core/nm-vpn-dbus-types.xml"/> + </section> </chapter> <chapter id="ref-settings"> diff --git a/libnm-core/Makefile.am b/libnm-core/Makefile.am index 4ae3ce00f8..c4d348aa75 100644 --- a/libnm-core/Makefile.am +++ b/libnm-core/Makefile.am @@ -55,5 +55,11 @@ libnm_core_la_SOURCES += crypto_nss.c libnm_core_la_LIBADD += $(NSS_LIBS) endif -BUILT_SOURCES = $(GLIB_GENERATED) +nm-vpn-dbus-types.xml: nm-vpn-dbus-interface.h $(top_srcdir)/tools/enums-to-docbook.pl + $(AM_V_GEN) @PERL@ $(top_srcdir)/tools/enums-to-docbook.pl 'nm-vpn-dbus-types' 'VPN Plugin D-Bus API Types' $^ >$@ + +nm-dbus-types.xml: nm-dbus-interface.h $(top_srcdir)/tools/enums-to-docbook.pl + $(AM_V_GEN) @PERL@ $(top_srcdir)/tools/enums-to-docbook.pl 'nm-dbus-types' 'NetworkManager D-Bus API Types' $^ >$@ + +BUILT_SOURCES = $(GLIB_GENERATED) nm-vpn-dbus-types.xml nm-dbus-types.xml CLEANFILES = $(BUILT_SOURCES) diff --git a/tools/enums-to-docbook.pl b/tools/enums-to-docbook.pl new file mode 100755 index 0000000000..d3d8c33c32 --- /dev/null +++ b/tools/enums-to-docbook.pl @@ -0,0 +1,198 @@ +#!/usr/bin/perl -n + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +# +# +# Copyright 2016 Red Hat, Inc. +# + +# This tool formats enums along with their Gtk-Doc comments from a header +# file and produces a Docbook refentry suitable for inclusion in the D-Bus +# API rederence documentation. +# +# The output differs from Gtk-Doc: only enums are considered and are +# printed along with the values that are need to stay stable. + +use strict; +use warnings; + +our $name; +our $desc; +our $choice; +our @choices; +our $val; + +BEGIN { +my $id = shift @ARGV or die "Missing ID"; +my $nm = shift @ARGV or die "Missing title"; +print <<END; +<?xml version='1.0'?> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<refentry id="$id"> + <refmeta> + <refentrytitle role="top_of_page" id="$id.top_of_page">$nm</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>$nm</refmiscinfo> + </refmeta> + <refnamediv> + <refname>$nm</refname> + <refpurpose></refpurpose> + </refnamediv> + +END +} + +# Increment a value keeping the format (e.g. 0x000666 is incremented to 0x000667, +# while 9 becomes 10. +sub inc +{ + my $val = shift; + + if ($val =~ /^\d+$/) { + my $len = length $val; + return sprintf "%0${len}d", $val + 1; + } elsif ($val =~ /^0x(.+)$/) { + my $len = length $1; + return sprintf "0x%0${len}x", hex ($1) + 1; + } + die "'$val' used in previous enum value can not be incremented"; +} + +# The Gtk-Doc to docbook translation happens here. We don't support +# everything Gtk-Doc does. +sub fmt +{ + $_ = shift; + s/\#([^\s\.]+)/<link linkend="$1">$1<\/link>/gm; + s/\s*(.*)/<para>$1<\/para>/gm; + $_; +} + +chomp; + +if (/^\/\*\*$/) { + # Start of a documentation comment + $name = ''; + $desc = ''; + $choice = undef; + @choices = (); +} elsif (/^ \* (.+):$/) { + # The name + die "Duplicate name '$1': already processing '$name'" if $name; + $name = $1; +} elsif (/^ \* @(\S+):\s+(.*)$/) { + # The enum choice documentation + $choice = $1; + die "Documentation for '$1' already seen" if grep { $_->[0] eq $choice } @choices; + push @choices, [ $choice, $2 ] +} elsif (/^ \*\s+(.*)$/) { + # Text. Either a choice documentation, a description or continuation of either + if (defined $choice) { + my ($this) = grep { $_->[0] eq $choice } @choices; + $this->[1] .= " $1"; + } elsif (defined $desc) { + $desc .= " " if $desc; + $desc .= $1; + } +} elsif (/^ \*$/) { + # A separator line. Either starts the description or breaks a paragraph. + $desc .= "\n" if $desc; + $choice = undef; +} elsif (/^ \*+\/$/) { + # End of the doc comment + $choice = undef; +} elsif (/^typedef enum/) { + # Start of an enum + $val = 0; +} elsif (/^\s+(\S+)\s+=\s+([^,\s]+)/) { + # A choice with a literal value + next unless @choices; + die "Saw enum value '$1', but didn't see start of enum before" unless defined $val; + $val = $2; + my ($this) = grep { $_->[0] eq $1 } @choices; + die "Documentation for value '$1' missing" unless $this; + $this->[2] = "= <literal>$val</literal>"; +} elsif (/^\s+([^,\s]+),?$/) { + # A choice without a literal value + next unless @choices; + die "Saw enum value '$1', but didn't see start of enum before" unless defined $val; + my ($this) = grep { $_->[0] eq $1 } @choices; + die "Documentation for value '$1' missing" unless $this; + $val = inc $val; + $this->[2] = "= <literal>$val</literal>"; +} elsif (/^\} ([^;]+);/) { + # End of an enum + next unless defined $name; + die "Name of the enum '$1' different than documented '$name'" if $1 ne $name; + + @choices = grep { $_->[0] !~ /_LAST$/ } @choices; + foreach (@choices) { + die "'$_->[0]' documented, but not present in enum" unless defined $_->[2] + } + + $desc = fmt $desc; + print <<END; + <refsect2 id="$name" role="enum"> + <title>enum $name</title> + <indexterm zone="$name"> + <primary>$name</primary> + </indexterm> + <para>$desc</para> + <refsect3 role="enum_members"> + <title>Values</title> + <informaltable role="enum_members_table" pgwide="1" frame="none"> + <tgroup cols="4"> + <colspec colname="enum_members_name" colwidth="300px" /> + <colspec colname="enum_members_value" colwidth="100px"/> + <colspec colname="enum_members_description" /> + <tbody> +END + foreach (@choices) { + my ($name, $desc, $val) = map { fmt $_ } @$_; + print <<END; } + <row role="constant"> + <entry role="enum_member_name">$name</entry> + <entry role="enum_member_value">$val</entry> + <entry role="enum_member_description">$desc</entry> + </row> +END + print <<END; + </tbody> + </tgroup> + </informaltable> + </refsect3> + </refsect2> + +END + + $name = undef; + $desc = undef; + $choice = undef; + $val = undef; + @choices = (); +} else { + # Only care about other lines if we're parsing an enum + next unless $val; + s/\/\*.*\*\///g; + die "Unexpected input '$_' while parsing enum" unless /^\s*$/; +} + +END { +print <<END; +</refentry> +END +} |