giscanner: don't accept (allow-none) on Returns:

The old annotationparser.py happily parsed this, but
giscanner/girwriter.py never serialized an allow-none
attribute to the .gir file and girepository/girparser.c
never looked for an allow-none attribute either.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
maintransformer: split up a complex conditional

We assign node.allow_none in two separate cases:

 - if the (allow-none) annotation was given

 - for GCancellable and GAsyncReadyCallback, as special cases

Split the two up.  This will simplify future commits.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
giscanner: tweak GCancellable null special case

We treat GCancellable and GAsyncReadyCallback as if they were always
tagged (allow-none) because these parameters universally allow %NULL to
be given as a value when they appear as in parameters on functions.

Unfortunately, the meaning of (allow-none) is different on out
parameters.  There it means that you can give %NULL to ignore the return
value.

Limit this special case to only in parameters.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
giscanner: change some internal field logic

Replace the 'allow_none' field on parameters with two separate fields:
'nullable' and 'optional'.

Currently, we use 'nullable' to mean the same thing as 'allow-none' for
normal (non-out) parameters.  For out parameters, we use the 'optional'
field instead.

Note that the special case for GCancellable and GAsyncReadyCallback is
already guarded by a check for being an in parameter, so we always use
'nullable' here.

On the .gir writer side, we decide which variable to consult when
writing the allow-none attribute depending on the parameter direction.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
giscanner: write nullable and optional attributes

Record our internal 'nullable' and 'optional' attributes into the
written .gir file.  It is now theoretically possible to express the
concept of an out parameter with a nullable type (although presently
there is no way to do this).

Modify our own internal parser (in the scanner) to understand the
newly-written attributes.

Update the expected output of the 'Regress-1.0.gir' test to account for
the new attributes.

Nothing else understands 'nullable' yet, but the girparser in the
typelib compiler already understands 'optional' and records a bit for it
in the typelib.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
giscanner: add (nullable) and (optional) annotations

Add two new annotations, (nullable) and (optional).

(nullable) always means "the type of this value can also contain null".

(optional) always means "this out parameter can be ignored by passing
NULL to the C function".

https://bugzilla.gnome.org/show_bug.cgi?id=660879
giscanner: support nullable return types too

Promote the 'nullable' field to the TypeContainer base class (which is
shared by Return and Parameter types).

Add .gir support for nullability on return values, both in the writer
and in the (scanner's) parser.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
girepository: ArgBlob: rename allow_none parameter

Rename the "allow_none" parameter on internal/private structure ArgBlob
to "nullable".

This is a straight rename with no other changes.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
compiler: girparser: parse 'nullable' attribute

Parse the 'nullable' attribute on parameters and function return types.

Additionally, tweak the meaning of the 'allow-none' attribute.  We now
only treat it as equivalent to 'nullable' for non-out parameters.  For
out parameters, we treat it to mean the same as the already-recognised
'optional' parameter (which we only recently started actually using).

https://bugzilla.gnome.org/show_bug.cgi?id=660879
giscanner: fix a comparison

In the case that a parameter has not been explicitly annotated, the
value of node.direction will be None, not 'in'.  Instead of comparing as
== 'in' we should therefore check for being != 'out'.

https://bugzilla.gnome.org/show_bug.cgi?id=660879
Revert "giscanner: don't accept (allow-none) on Returns:"

This reverts commit 0839e696e9fbc1942ac5c61054de3b47e9578152.

This was accidentally picked up by my 'git bz apply' against the bug as
I was getting ready to push the last set of changes.
giscanner: allow (nullable) and (optional)

Add (nullable) and (optional) as recognised annotations in the same places that
(allow-none) is allowed.  This should have been done in the previous
commits but the tests were passing because the only ill effect was that
a warning was issued.
tests: fix Regress expected output

Now that Cancellable and AsyncReadyCallback are being correctly
recognised again, adjust the expected output of the Regress testcase.
annotationparser: more nullable fixes

Add ANN_NULLABLE and ANN_OPTIONAL in the one (and only) other place that
ANN_ALLOW_NONE is mentioned...
girepository: change giarginfo docs

Clarify the meaning of 'may be null' in the docs: it refers to the value
of the argument itself, not the reference to the argument.

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