[yargs] Fix example and middleware types (flow-typed#4511)

* improve example

* fix middleware return type

definitions/npm/yargs_v17.x.x/flow_v0.201.x-/yargs_v17.x.x.js

@@ -64,8 +64,12 @@ declare module "yargs" {
     | ModuleObjectDescribe
     | ModuleObjectDescription;
 
-  declare type MiddleWareCallback =
-    | (argv: Argv, yargsInstance?: Yargs) => void
+  declare type MiddleWareCallback = (argv: Argv, yargsInstance?: Yargs) => (
+    void
+    | Promise<void>
+    | { ... }
+    | Promise<{ ... }>
+  )
     | (argv: Argv, yargsInstance?: Yargs) => Promise<void>;
 
   declare type Middleware = MiddleWareCallback | Array<MiddleWareCallback>;
@@ -186,6 +190,7 @@ declare module "yargs" {
     epilogue(text: string): this;
 
     example(cmd: string, desc?: string): this;
+    example(examples: Array<[string, string | void]>): this;
 
     exitProcess(enable: boolean): this;
 
@@ -334,6 +339,8 @@ declare module "yargs" {
     wrap(columns: number | null): this;
   }
 
+  declare type YargsType = Yargs;
+
   declare module.exports: Yargs;
 }
 

definitions/npm/yargs_v17.x.x/test_yargs.js

@@ -1,7 +1,7 @@
 // @flow
 
 import { describe, it, test } from 'flow-typed-test';
-import yargs from 'yargs';
+import yargs, { type YargsType, type Argv } from 'yargs';
 const { hideBin } = require('yargs/helpers');
 
 describe('command()', () => {
@@ -37,6 +37,43 @@ describe('command()', () => {
 
   it('example', () => {
     yargs.example('fetch', 'fetch [...files]');
+    yargs.example('fetch');
+
+    yargs.example([
+      ['fetch', 'fetch [...files]'],
+      ['fetch', 'fetch [...files]'],
+      ['fetch', undefined],
+    ]);
+
+    // $FlowExpectedError[incompatible-call]
+    yargs.example();
+    // $FlowExpectedError[incompatible-call]
+    yargs.example(1);
+    // $FlowExpectedError[incompatible-call]
+    yargs.example('fetch', 1);
+    // $FlowExpectedError[incompatible-call]
+    yargs.example([
+      [],
+    ]);
+    // $FlowExpectedError[incompatible-call]
+    yargs.example([1]);
+  });
+
+  it('middleware', () => {
+    yargs.middleware(() => {});
+    yargs.middleware(async () => {});
+    yargs.middleware(() => { return { runAll: true } });
+    yargs.middleware(async () => { return { runAll: true }});
+
+    yargs.middleware((args, innerYargs) => {
+      (args: Argv);
+      (innerYargs: YargsType | void);
+    });
+
+    // $FlowExpectedError[incompatible-call]
+    yargs.middleware();
+    // $FlowExpectedError[incompatible-call]
+    yargs.middleware(() => 1);
   });
 });