[Vala] vapi docs

[pancake <pancake youterm com>]

After reading the VAPI reference website I find it useful but missed some
extra documentation for methods, fields and so on. Because reading the
website is just the same as reading the vapi file with no extra benefits.

I wonder if it would be possible to add inline documentation or annotations
in the vapi files that can be reflected in the generated vapidoc web 
interface.

I always thought if it would be better to have the documentation outside
the vapi files (like specifying an extern directory or file) containing the
textual information describing the methods and attributes. Because
vapi files are fine as they are (code only) and add documentation there can
make them so much innecesarily bloated.

In this way it would be possible to get the documentation like in devhelp.

--pancake