erunion / mill

☴ An annotation-based DSL for documenting a REST API.
MIT License
39 stars 2 forks source link

Markdown links in param descriptions collide with enums #53

Closed erunion closed 7 years ago

erunion commented 7 years ago
@api-param {string} content_rating +MOVIE_RATINGS+ 
    [MPAA rating](http://www.mpaa.org/film-ratings/)

Having a parameter description with a Markdown link causes the link to get parsed without the link content.

[
    'capability' => 'MOVIE_RATINGS'
    'deprecated' => false
    'description' => '(http://www.mpaa.org/film-ratings/)'
    'field' => 'content_rating'
    'required' => true
    'type' => 'string'
    'values' => Array &1 (
        0 => 'MPAA rating'
    )
    'version' => false
    'visible' => true
]
erunion commented 7 years ago

This is going to have to be built without messing up the enum capability as well:

@api-param {string} content_rating [G|PG|PG-13|R] 
    [MPAA rating](http://www.mpaa.org/film-ratings/)

Might be able to get away with running a Markdown to HTML conversion on the parameter content, and go through with parsing, and then convert HTML back to Markdown? That's a bit messy, though.

erunion commented 7 years ago

Turns out it was easier to fix than I thought by just restricting the enum regex to not be so global.