gtkdoc-scan supports regular expressions in the --ignore-decorators
command-line option. Since it is easier to use a regexp than grepping
macros from a source file, revert the ugly solution from commit
2d941dc95a1d ('build: fix errors when building with gtk-doc 1.32').

gtkdoc-scan 1.32 performs stricter checks on structures definitions
and so it complains on:

 /build/networkmanager/src/NetworkManager/libnm/./nm-vpn-plugin-old.h:0: warning: partial declaration (struct) : typedef struct {
 	NM_DEPRECATED_IN_1_2
 	GObject parent;
 } NMVpnPluginOld NM_DEPRECATED_IN_1_2;

because of the unrecognized token 'NM_DEPRECATED_IN_1_2'.

Pass all allowed macros to gtkdoc-scan through the --ignore-decorators
argument.

https://gitlab.gnome.org/GNOME/gtk-doc/issues/98
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/238

In libnm, we prefer opaque typedefs. gtk-doc needs to be patched to properly
generate documentation. Add a check for that.

Add a test. By default, this does not fail but just prints a warning. The test
can be made failing by setting NMTST_CHECK_GTK_DOC=1.

See-also: https://gitlab.gnome.org/GNOME/gtk-doc/merge_requests/2
(cherry picked from commit 02464c052e2f8a1e88b012e0a29f5f66fce310ad)

There are two aspects: the public crypto API that is provided by
"nm-crypto.h" header, and the internal header which crypto backends
need to implement. Split them.

"crypto.h" did not follow our common NM style naming. Rename
the files.

Shared libraries built with sanitizers are a bit inconvenient to use
because they require that any application linking to them is run with
libasan preloaded using LD_PRELOAD. This limitation makes the
sanitizer support less useful because applications will refuse to
start unless there is a special environment variable set.

Let's turn the --enable-address-sanitizer configure flag into
--with-address-sanitizer=yes|no|exec so that is possible to enable
asan only for executables.

We commonly only allow tabs at the beginning of a line, not
afterwards. The reason for this style is so that the code
looks formated right with tabstop=4 and tabstop=8.

It already defaults to the right value. We only need to define
NM_VERSION_MIN_REQUIRED, so that parts of our internal build
can make use of deprecated API.

We don't need to have two version defines "CUR" and "NEXT".

The main purpose of these macros (if not their only), is to
make NM_AVAILABLE_IN_* and NM_DEPRECATED_IN_* macros work.

1) At the precise commit of a release, "CUR" and "NEXT" must be identical,
because whenever the user configures NM_VERSION_MIN_REQUIRED and
NM_VERSION_MAX_ALLOWED, then they both compare against the current
version, at which point "CUR" == "NEXT".

2) Every other commit aside the release, is a development version that leads
up the the next coming release. But as far as versioning is concerned, such
a development version should be treated like that future release. It's unstable
API and it may or may not be close to later API of the release. But
we shall treat it as that version. Hence, also in this case, we want to
set both "NM_VERSION_CUR_STABLE" and again NEXT to the future version.

This makes NM_VERSION_NEXT_STABLE redundant.

Previously, the separation between current and next version would for
example allow that NM_VERSION_CUR_STABLE is the previously release
stable API, and NM_VERSION_NEXT_STABLE is the version of the next upcoming
stable API. So, we could allow "examples" to make use of development
API, but other(?) internal code still restrict to unstable API. But it's
unclear which other code would want to avoid current development.

Also, the points 1) and 2) were badly understood. Note that for our
previousy releases, we usually didn't bump the macros at the stable
release (and if we did, we didn't set them to be the same). While using
two macros might be more powerful, it is hard to grok and easy to
forget to bump the macros a the right time. One macro shall suffice.

All this also means, that *immediately* after making a new release, we shall
bump the version number in `configure.ac` and "NM_VERSION_CUR_STABLE".

RHEL 7.1 and Ubuntu 14.04 LTS both have this.

https://bugzilla.gnome.org/show_bug.cgi?id=792323