From 7d12e1aee4ebf0b108af2fb048e9fb7c35c2b144 Mon Sep 17 00:00:00 2001
From: bcoe <bencoe@google.com>
Date: Sun, 28 Jul 2019 19:25:55 -0700
Subject: [PATCH] review: flesh out TypeScript docs a bit further

---
 README.md          |  5 +++--
 docs/typescript.md | 19 +++++++++++++------
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 86dccba60..2132e9b1a 100644
--- a/README.md
+++ b/README.md
@@ -89,10 +89,10 @@ Run the example above with `--help` to see the help for the application.
 
 ## TypeScript
 
-yargs has type definitions at `@types/yargs`
+yargs has type definitions at [@types/yargs][type-definitions].
 
 ```
-npm i -D @types/yargs
+npm i --development @types/yargs
 ```
 
 See usage examples in [docs](/docs/typescript.md)
@@ -132,3 +132,4 @@ Having problems? want to contribute? join our [community slack](http://devtoolsc
 [conventional-commits-url]: https://conventionalcommits.org/
 [slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg
 [slack-url]: http://devtoolscommunity.herokuapp.com
+[type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs
diff --git a/docs/typescript.md b/docs/typescript.md
index 257106b2d..ada3572fc 100644
--- a/docs/typescript.md
+++ b/docs/typescript.md
@@ -1,6 +1,9 @@
 # TypeScript usage examples
 
-Options type inference work pretty well
+The TypeScript definitions take into account yargs' `type` key and the prescense of
+`demandOption`/`default`.
+
+The following `.options()` definition:
 
 ```typescript
 #!/usr/bin/env node
@@ -14,9 +17,10 @@ const argv = yargs.options({
   e: { type: 'count' },
   f: { choices: ['1', '2', '3'] }
 }).argv;
-
 ```
-`argv` will get type
+
+Will result in an `argv` that's typed like so:
+
 ```typescript
 {
   [x: string]: unknown;
@@ -31,7 +35,10 @@ const argv = yargs.options({
 }
 ```
 
-You might want to declare an interface for arguments object
+
+You will likely want to define an interface for your application, describing the form that
+the parsed `argv` will take:
+
 ```typescript
 interface Arguments {
   [x: string]: unknown;
@@ -44,7 +51,7 @@ interface Arguments {
 }
 ```
 
-To improve `choices` option typing you can specify type for choices
+To improve the `choices` option typing you can also specify its types:
 
 ```typescript
 type Difficulty = 'normal' | 'nightmare' | 'hell';
@@ -56,4 +63,4 @@ const argv = yargs.option('difficulty', {
 }).argv;
 ```
 
-`argv` will get  type `'normal' | 'nightmare' | 'hell'`
+`argv` will get  type `'normal' | 'nightmare' | 'hell'`.