Change `docs.sort` from a comma-separated string to an array of strings

[lazarljubenovic]

Currently, the docs.sort option in the CLI accepts a string for determining the sort order, e.g. "access, scope".

However, it's much easier to parse, validate, provide type-safety, and offer auto-completion in the IDE when the expected type is an array of enumerated valid strings.

In TypeScript (not sure about Flow):

type SortProp = 'access' | 'scope' | 'type' | 'name'
type Sort = Array<SortProp>

const sort: Sort = ['acess'] // oops!

instead of

type Sort = string

const sort: Sort = 'acess, foo, bar' // only runtime error

In JSON schema:

    "sort": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["access", "scope", "type", "name"],
        "uniqueItems": true
      },
      "description": "An array of properties to sort by. Valid properties are: “access”, “scope”, “type” and “name”."
    }

instead of

        "sort": {
          "type": "string",
          "description": "A comma-separated string of properties to sort by. Valid properties are: “access”, “scope”, “type” and “name”."
        }

---

Not sure what the deprecation policies are at this young stage of the project, but it wouldn't be difficult to support both for a while and print a warning that the string syntax will be removed in the next major version.

[ShukantPal]

Yeah, this makes sense.

[ShukantPal]

This will probably go into 1.1.7 or 1.2.0 (whichever comes first)