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 @@ +
+ Types + + +
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 < + + + + + + $nm + 3 + $nm + + + $nm + + + +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\.]+)/$1<\/link>/gm; + s/\s*(.*)/$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] = "= $val"; +} 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] = "= $val"; +} 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 < + enum $name + + $name + + $desc + + Values + + + + + + +END + foreach (@choices) { + my ($name, $desc, $val) = map { fmt $_ } @$_; + print < + $name + $val + $desc + +END + print < + + + + + +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 +}