giscanner: fix GTK-Doc comment block parsing

- GTK-Doc and current g-ir-scanner do not allow tags to be written before the
  comment block description but old version of g-ir-scanner parsed that just
  file. Fix this regression, but emit when tags are encountered at the wrong
  location. #674658

- During this analysis, a secondary bug report was filed with the GTK-Doc
  project because it was found that the same malformed tags did not result
  in the expected html output.

  After discussing this with the GTK-Doc maintainers, we learned
  that our g-i specific top level tags should never have existed
  in the first place. The prefered notation for annotations that
  apply to the identifier should be written on the identifier line,
  for example like what we already do with (skip).

  As a result, this patch deprecates g-i specific top level tags and
  implements them as annotations on the identifier instead and at
  the same time adds support for malformed comment blocks still
  using g-i specific top level tags.

  This means that all annotated code "out there" will continue to work
  just fine with this version of g-i, but when a developer decides to
  fix deprecation warnings in his/her comment blocks, the dependency
  on g-i needs to be raised to a version that contains at least this
  patch. #676133

- I previously (and foolishly) removed parentheses matching with
  a regex, which off course is not possible when there are multiple
  nested levels of parens (which we will now see more with annotations
  on the identifier, for example with the type annotation). Remove
  the "annotation parens matching" regexes again and add in more
  warnings on unbalanced/unexpected parentheses. #688897

https://bugzilla.gnome.org/show_bug.cgi?id=674658
https://bugzilla.gnome.org/show_bug.cgi?id=676133
https://bugzilla.gnome.org/show_bug.cgi?id=688897
giscanner: Fix description field storage in .gir files

GTK-Doc description fields for tags can contain multiple lines and
even multiple paragraphs. Whitespace cannot be preserved in XML
attributes, so we move the "deprecated" description text into
a "<doc-deprecated />" element right next to where we already have
the "<doc />" element. Keep the "deprecated" attribute around for
backwards compatibility though, but set its value to "1" (analogous
to the "writable", "contruct", etc attributes) if the annotated
symbol is marked as deprecated.

While at it, add <doc-version /> and <doc-stability /> which
was not yet available in the .gir files...

This takes care of the "Since:", "Stability:" and "Deprecated:"
GTK-Doc tags. Nothing needs to be done the "Returns:" tag as
as we already write a "<doc />" child element on "<return-value />".
Add a tool fixing GTK-Doc comment blocks in .c and .h files

Just a standalone script for now, should probably eventually
go into g-ir-doctool or g-ir-annotation-tool...
docs: document some annotationparser.py hacking hints

https://bugzilla.gnome.org/show_bug.cgi?id=688897
Add giscanner package documentation

Using Sphinx [1] markup for now. We eventually might want
to add GTK-Doc support for python and dogfood g-ir-doctool
on this package.

[1] De facto standard Python documentaton tool: http://sphinx-doc.org

https://bugzilla.gnome.org/show_bug.cgi?id=688897
g-ir-compiler: remove references to --code, remove --no-init options

The "--code" option was removed years ago in ac81f3e8c5f1c380d16677232d67466e739da283
so remove references to it from README and g-ir-compiler(1)

Remove the "--no-init" option from g-ir-compiler and g-ir-compiler(1)
as it was documented to "can only be used if --code is also specified",
so no reason to keep it around.
build: actually require libffi >= 3.0.0

as documented in README...
README: fix the Tools section a bit
[WIP] docs: improve layout
!!! for testing only !!!