[Vala] metadata file format

[tecywiz121 <tecywiz121 hotmail com>]

So, I'm a little sick and tired of not being able to find a reference on
the metadata file format used when binding a library, so I'm going to
list what I know about it so far.  Please amend/comment at will :)

Just note that this list is very incomplete and only lists what I have
used and/or found on the Bindings wiki page.

==The basic format==

* Comments:

        Comments start with a # and end at the end of a line.  For
        example:

        # this is a comment

* Other lines

        Every non-comment line in the file is made of up two sections:
        the specifier, and the parameters.

        The specifier is the first text to appear on the line, and it
        specifies what the rest of the line will be modifying.

        The parameters are a space separated list of a parameter name,
        followed by an equals sign and the value enclosed in quotes.

        For example, this line sets parameter1 and parameter2 on
        foo.bar:

        foo.bar parameter1="value" parameter2="value"

* Specifiers

        Specifiers always use the C-name for whatever it is you are
        modifying. For example if your namespace is Foo, and the vala
        name for the type is Bar, then you would use FooBar.

        Specifiers may also use wildcards, and all items that partially
        match the specifier will be selected.  For example:

        *.klass hidden="1"

        will hide the klass field in all types.

* Specifying Different Things

        To specify a:

        Function        - name_of_function

        Type            - Type

        Property        - Type:property_name

        Signal          - Type::signal_name

        Field           - Type.field_name

* Some Examples

        Hide a:

        Type            - Foo hidden="1"

        Function        - some_function hidden="1"

        Field           - Foo.bar hidden="1"

==Properties Reference==

The format for the entires will be like so

Name:           foobar
Applies To:     Signal, Method, Class, Struct, etc
Values:         The acceptable values
Description:    The description goes here.

**NOTE:  When "Return" is specified in the "Applies To" section, it
means that the property may be applied to a function, signal or delegate
to modify the return type.

And in no particular order:

Name:           hidden
Applies To:     Signal, Method, Class, Struct, Delegate, Property,
                Field, etc
Values:         0, 1
Description:    Causes the selected thing to not be output in the vapi
                file.

Name:           type_name
Applies To:     Parameter, Field, Return, Property
Values:         Any valid type
Description:    Changes the type of the selected thing

Name:           is_ref
Applies To:     Parameter
Values:         0, 1
Description:    Marks the parameter as "ref"

Name:           is_out
Applies To:     Parameter
Values:         0, 1
Description:    Marks the parameter as "out"

Name:           no_array_length
Applies To:     Function
Values:         0, 1
Description:    Does not implicitly pass array length to function

Name:           transfer_ownership
Applies To:     Return, Parameter
Values:         0, 1
Description:    Transfers ownership of the value

Name:           is_value_type
Applies To:     Type
Values:         0, 1
Description:    Marks type as a value type (aka struct)

Name:           weak
Applies To:     Field
Values:         0, 1
Description:    Marks the field as weak

Name:           name
Applies To:     Function, Parameter, Class, Struct, Property, Signal,
                Field, Enum
Values:         Any valid identifier
Description:    Changes the name of the thing, does not change namespace

Name:           namespace
Applies To:     Type
Values:         Any namespace
Description:    Changes the namespace of the thing

Name:           nullable
Applies To:     Field, Property, Parameter, Return
Values:         0, 1
Description:    Marks the value as nullable

Name:           ellipsis
Applies To:     Function
Values:         0, 1
Description:    Marks that the function has a variable argument list


Name:           type_arguments
Applies To:     Return, Signal
Values:         Any valid type
Description:    Restricts the generic type of the thing

Name:           errordomain
Applies To:     Enum
Values:         0, 1
Description:    Marks the enumeration as a GError domain

Name:           throws
Applies To:     Function
Values:         0, 1
Description:    Marks that the function should use an out parameter
                instead of throwing an error

Name:           base_class
Applies To:     Class
Values:         Any inheritable type
Description:    Marks the base class for the type

Name:           rename_to
Applies To:     Class, Struct, Enum
Values:         Any valid identifier
Description:    Renames the type to something else, ie fooFloat to float

Name:           common_prefix
Applies To:     Enum
Values:         Any string
Description:    Removes a common prefix from enumeration values

Name:           cheader_filename
Applies To:     Anything
Values:         Header include path
Description:    Compiler will adds the specified header when thing is
                used.

Name:           deprecated
Applies To:     Anything
Values:         0, 1
Description:    Marks the thing as deprecated

Name:           deprecated_since
Applies To:     Anything
Values:         Date
Description:    Marks the thing as deprecated

Name:           replacement
Applies To:     Anything
Values:         The thing that replaces this
Description:    Specifies a replacement

Name:           free_function
Applies To:     Struct, Boxed
Values:         the full C-name of the free function
Description:    Sets a free function for the struct

Name:           simple_type
Applies To:     Struct
Values:         0, 1
Description:    Marks the struct as being a simple type, like int

Name:           base_type
Applies To:     Struct
Values:         Any type that a struct can inherit from
Description:    Marks the struct as inheriting

Name:           rank
Applies To:     Struct
Values:         Any integer
Description:    I have no idea

Name:           immutable
Applies To:     Struct, Boxed
Values:         0, 1
Description:    Marks the thing as immutable

Name:           has_copy_function
Applies To:     Struct, Boxed
Values:         0, 1
Description:    marks the struct as having a copy function

Name:           has_type_id
Applies To:     Struct, Boxed
Values:         0, 1
Description:    marks the thing as having a type id

Name:           is_array
Applies To:     Return, Property, Parameter, Field
Values:         0, 1
Description:    Marks the thing as an array

Name:           array_length_pos
Applies To:     Parameter
Values:         x.y where is the parameter location, and y is 9 (???)
Description:    Sets the position of the length for the parameter,
                length needs to be hidden separately.

Name:           default_value
Applies To:     Parameter
Values:         Any values that would be valid for the type
Description:    Sets the default value for a parameter.