Add improved docs

Author: wooorm

lib/options.js

@@ -43,9 +43,9 @@ const minischema = {
   default: {},
   /** @type {Record<string, string>} */
   alias: {},
-  /** @type {string[]} */
+  /** @type {Array<string>} */
   string: [],
-  /** @type {string[]} */
+  /** @type {Array<string>} */
   boolean: []
 }
 
@@ -57,7 +57,7 @@ while (++index < schema.length) {
 /**
  * Parse CLI options.
  *
- * @param {string[]} flags
+ * @param {Array<string>} flags
  * @param {Options} configuration
  */
 export function options(flags, configuration) {
@@ -152,8 +152,8 @@ function addEach(option) {
 /**
  * Parse `extensions`.
  *
- * @param {string[]|string|null|undefined} value
- * @returns {string[]}
+ * @param {Array<string>|string|null|undefined} value
+ * @returns {Array<string>}
  */
 function commaSeparated(value) {
   return flatten(normalize(value).map((d) => splitList(d)))
@@ -162,7 +162,7 @@ function commaSeparated(value) {
 /**
  * Parse `plugins`.
  *
- * @param {string[]|string|null|undefined} value
+ * @param {Array<string>|string|null|undefined} value
  * @returns {Record<string, Record<string, unknown>|undefined>}
  */
 function plugins(value) {
@@ -182,7 +182,7 @@ function plugins(value) {
 /**
  * Parse `reporter`: only one is accepted.
  *
- * @param {string[]|string|null|undefined} value
+ * @param {Array<string>|string|null|undefined} value
  * @returns {[string|undefined, Record<string, unknown>|undefined]}
  */
 function reporter(value) {
@@ -201,7 +201,7 @@ function reporter(value) {
 /**
  * Parse `settings`.
  *
- * @param {string[]|string|null|undefined} value
+ * @param {Array<string>|string|null|undefined} value
  * @returns {Record<string, unknown>}
  */
 function settings(value) {
@@ -293,7 +293,7 @@ function handleUnknownArgument(flag) {
 /**
  * Inspect all `options`.
  *
- * @param {Option[]} options
+ * @param {Array<Option>} options
  * @returns {string}
  */
 function inspectAll(options) {
@@ -304,7 +304,7 @@ function inspectAll(options) {
  * Inspect one `option`.
  *
  * @param {Option} option
- * @returns {string[]}
+ * @returns {Array<string>}
  */
 function inspect(option) {
   let description = option.description
@@ -326,8 +326,8 @@ function inspect(option) {
 /**
  * Normalize `value`.
  *
- * @param {string[]|string|null|undefined} value
- * @returns {string[]}
+ * @param {Array<string>|string|null|undefined} value
+ * @returns {Array<string>}
  */
 function normalize(value) {
   if (!value) {
@@ -344,8 +344,8 @@ function normalize(value) {
 /**
  * Flatten `values`.
  *
- * @param {string|string[]|string[][]} values
- * @returns {string[]}
+ * @param {string|Array<string>|Array<Array<string>>} values
+ * @returns {Array<string>}
  */
 function flatten(values) {
   // @ts-expect-error: TS is wrong.
@@ -354,15 +354,15 @@ function flatten(values) {
 
 /**
  * @param {string} value
- * @returns {string[]}
+ * @returns {Array<string>}
  */
 function splitOptions(value) {
   return value.split('=')
 }
 
 /**
  * @param {string} value
- * @returns {string[]}
+ * @returns {Array<string>}
  */
 function splitList(value) {
   return value.split(',')

lib/schema.js

@@ -9,7 +9,7 @@
  * @property {boolean} [truelike=false]
  */
 
-/** @type {Option[]} */
+/** @type {Array<Option>} */
 export const schema = [
   {
     long: 'help',