Provide JSDoc comments for flag properties (#230)

index.d.ts

@@ -16,13 +16,93 @@ Callback function to determine if a flag is required during runtime.
 export type IsRequiredPredicate = (flags: Readonly<AnyFlags>, input: readonly string[]) => boolean;
 
 export type Flag<PrimitiveType extends FlagType, Type, IsMultiple = false> = {
+ /**
+ Type of value. (Possible values: `string` `boolean` `number`)
+ */
  readonly type?: PrimitiveType;
- readonly shortFlag?: string;
+
+ /**
+ Limit valid values to a predefined set of choices.
+
+ @example
+ ```
+ unicorn: {
+ isMultiple: true,
+ choices: ['rainbow', 'cat', 'unicorn']
+ }
+ ```
+ */
+ readonly choices?: Type extends unknown[] ? Type : Type[];
+
+ /**
+ Default value when the flag is not specified.
+
+ @example
+ ```
+ unicorn: {
+ type: 'boolean',
+ default: true
+ }
+ ```
+ */
  readonly default?: Type;
- readonly isRequired?: boolean | IsRequiredPredicate;
- readonly isMultiple?: IsMultiple;
+
+ /**
+ A short flag alias.
+
+ @example
+ ```
+ unicorn: {
+ shortFlag: 'u'
+ }
+ ```
+ */
+ readonly shortFlag?: string;
+
+ /**
+ Other names for the flag.
+
+ @example
+ ```
+ unicorn: {
+ aliases: ['unicorns', 'uni']
+ }
+ ```
+ */
  readonly aliases?: string[];
- readonly choices?: Type extends unknown[] ? Type : Type[];
+
+ /**
+ Indicates a flag can be set multiple times. Values are turned into an array.
+
+ Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values [currently *not* supported](https://github.com/sindresorhus/meow/issues/164).
+
+ @default false
+ */
+ readonly isMultiple?: IsMultiple;
+
+ /**
+ Determine if the flag is required.
+
+ If it's only known at runtime whether the flag is required or not you can pass a Function instead of a boolean, which based on the given flags and other non-flag arguments should decide if the flag is required.
+
+ - The first argument is the **flags** object, which contains the flags converted to camel-case excluding aliases.
+ - The second argument is the **input** string array, which contains the non-flag arguments.
+ - The function should return a `boolean`, true if the flag is required, otherwise false.
+
+ @default false
+
+ @example
+ ```
+ isRequired: (flags, input) => {
+ if (flags.otherFlag) {
+ return true;
+ }
+
+ return false;
+ }
+ ```
+ */
+ readonly isRequired?: boolean | IsRequiredPredicate;
 };
 
 type StringFlag = Flag<'string', string> | Flag<'string', string[], true>;
@@ -43,14 +123,17 @@ export type Options<Flags extends AnyFlags> = {
  The key is the flag name in camel-case and the value is an object with any of:
 
  - `type`: Type of value. (Possible values: `string` `boolean` `number`)
- - `shortFlag`: A short flag alias.
+ - `choices`: Limit valid values to a predefined set of choices.
  - `default`: Default value when the flag is not specified.
- - `isRequired`: Determine if the flag is required.
- If it's only known at runtime whether the flag is required or not you can pass a Function instead of a boolean, which based on the given flags and other non-flag arguments should decide if the flag is required.
- - `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
- Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are *not* supported.
+ - `shortFlag`: A short flag alias.
  - `aliases`: Other names for the flag.
- - `choices`: Limit valid values to a predefined set of choices.
+ - `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
+ - Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values [currently *not* supported](https://github.com/sindresorhus/meow/issues/164).
+ - `isRequired`: Determine if the flag is required. (Default: false)
+ - If it's only known at runtime whether the flag is required or not, you can pass a `Function` instead of a `boolean`, which based on the given flags and other non-flag arguments, should decide if the flag is required. Two arguments are passed to the function:
+ - The first argument is the **flags** object, which contains the flags converted to camel-case excluding aliases.
+ - The second argument is the **input** string array, which contains the non-flag arguments.
+ - The function should return a `boolean`, true if the flag is required, otherwise false.
 
  Note that flags are always defined using a camel-case key (`myKey`), but will match arguments in kebab-case (`--my-key`).
 
@@ -59,18 +142,18 @@ export type Options<Flags extends AnyFlags> = {
  flags: {
  unicorn: {
  type: 'string',
- shortFlag: 'u',
+ choices: ['rainbow', 'cat', 'unicorn'],
  default: ['rainbow', 'cat'],
+ shortFlag: 'u',
+ aliases: ['unicorns']
  isMultiple: true,
- choices: ['rainbow', 'cat', 'unicorn'],
  isRequired: (flags, input) => {
  if (flags.otherFlag) {
  return true;
  }
 
  return false;
- },
- aliases: ['unicorns']
+ }
  }
  }
  ```

readme.md

@@ -103,17 +103,17 @@ Define argument flags.
 The key is the flag name in camel-case and the value is an object with any of:
 
 - `type`: Type of value. (Possible values: `string` `boolean` `number`)
-- `shortFlag`: A short flag alias.
+- `choices`: Limit valid values to a predefined set of choices.
 - `default`: Default value when the flag is not specified.
+- `shortFlag`: A short flag alias.
+- `aliases`: Other names for the flag.
+- `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
+ - Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are [currently *not* supported](https://github.com/sindresorhus/meow/issues/164).
 - `isRequired`: Determine if the flag is required. (Default: false)
  - If it's only known at runtime whether the flag is required or not, you can pass a `Function` instead of a `boolean`, which based on the given flags and other non-flag arguments, should decide if the flag is required. Two arguments are passed to the function:
  - The first argument is the **flags** object, which contains the flags converted to camel-case excluding aliases.
  - The second argument is the **input** string array, which contains the non-flag arguments.
  - The function should return a `boolean`, true if the flag is required, otherwise false.
-- `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
- - Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are [currently *not* supported](https://github.com/sindresorhus/meow/issues/164).
-- `aliases`: Other names for the flag.
-- `choices`: Limit valid values to a predefined set of choices.
 
 Note that flags are always defined using a camel-case key (`myKey`), but will match arguments in kebab-case (`--my-key`).
 
@@ -123,18 +123,18 @@ Example:
 flags: {
  unicorn: {
  type: 'string',
- shortFlag: 'u',
+ choices: ['rainbow', 'cat', 'unicorn'],
  default: ['rainbow', 'cat'],
+ shortFlag: 'u',
+ aliases: ['unicorns'],
  isMultiple: true,
- choices: ['rainbow', 'cat', 'unicorn'],
  isRequired: (flags, input) => {
  if (flags.otherFlag) {
  return true;
  }
 
  return false;
- },
- aliases: ['unicorns']
+ }
  }
 }
 ```