Replace the custom parameter and representation DSL with MSON

[erunion]

https://github.com/apiaryio/mson

Basically, we're running into issues adding new things (like examples) into the Mill DSL for @api-param and representation annotations (see #41). Instead of trying to reinvent the wheel ourselves, we should just move over to MSON and be done with it.

Advantages of MSON over our existing description DSL:

1. It's an open specification.
2. It's easy to use.
3. We didn't build it.

Disadvantages:

1. We'll need to build an MSON parser in PHP.

---

Solving this would be three parts:

• Build a Mill MSON-flavor syntax parser.
• Replace @api-param syntax with MSON
• Replace @api-field, @api-type, @api-label, and @api-options in representations with a single new @api-data annotation, that also uses MSON for describing the piece of data.

MSON flavor

Since we require capabilities, and writing enum/options/members on the same line as the parameter, we'll need to have our own MSON flavor:

@api-param:visibility field `example` (type, required, capability) - Description 
    + Members
        - `option1` - "option1" description
        - `option2` - "option2" description 

@api-data field `example` (type, required, capability) - Description
    + Members
        - `option1` - "option1" description
        - `option2` - "option2" description 

This should allow us to retain the core parts of MSON portability, while also retaining some flexibility for Mill-specific features like capabilities, and single line definitions.

Unfortunately, this means we'll need to build our own parser, but at least the spec part of this is easy to understand, and will be easy to implement.

@api-param

Swapping out the @api-param DSL for MSON would be relatively easy (pending an MSON parser) as all of that logic is contained within ParamAnnotation::parse. Instead of manually parsing the docblock with regex, we'd feed it into the MSON parser and get back our data, and then send that along to the overall Mill parsing engine.

For example:

@api-param:public {page}
@api-param:public {per_page}
@api-param:public {string} query Search query.
@api-param:public {sort} [relevant|date|alphabetical]
@api-param:public {direction} [asc|desc]

Will become:

@api-param:public page
@api-param:public per_page
@api-param:public query (string) - Search query.
@api-param:public sort [relevant|date|alphabetical]
@api-param:public direction [asc|desc]

@api-data

Doing the same will also be simple, since everything is contained within the FieldAnnotation:parser method.

@api-label Director
@api-field director
@api-type string
@api-version >=3.3

Will become:

@api-data director `JJ Abrams` (string) - Director
@api-version >=3.3

This'll allow us to cut back on the annotation complexity of representation data by killing @api-label, @api-field, @api-type, and @api-options.

[erunion]

Been thinking about this for a few days, and I wonder if it'd be better to go (with the exception of capabilities), full MSON.

We can't support entering in all of your parameters and representation data with one annotation because we still need to support decorators for individual items, but something like this might work:

@api-param:visibility field `example` (type, required, capability) - Description

And if you need to support enums, you could do this:

@api-param:visibility {
    field `example` (enum[string], required, capability) - Description 
        - `option 1` (default) - Option 1 description
        - `option 2` - Option 2 description
}

That would allow us to start documenting enums properly, without adding something like an @api-optionValue annotation that's been talked about in #7.

[Dashron]

I like it, it also gives us the ability to use alternatives down the line with custom parsers.

Maybe clearly label it as MSON in the annotation so people can add JSON schema or OpenAPI?

[erunion]

Updated the original sec to have better support for enum documenting.