Add documentation for TypingsGenerator.

iclanton · iclanton · commit 7b0bc3c29137 · 2020-03-11T18:10:38.000-07:00
diff --git a/libraries/typings-generator/README.md b/libraries/typings-generator/README.md
@@ -0,0 +1,117 @@
+# Typings Generator
+
+## Installation
+
+`npm install @rushstack/typings-generator --save-dev`
+
+## Overview
+
+This is a utility for generating typings for non-TS files. It can operate in either a single-run mode or
+a watch mode. It is designed to generate `.d.ts` files with a specified generation function for all files matching
+specified file extensions, with an option to ignore individual files.
+
+## Usage
+
+```TypeScript
+import { TypingsGenerator } from '@rushstack/typings-generator';
+
+const typingsGenerator: TypingsGenerator = new TypingsGenerator({
+  srcFolder: '/repo/package/src',
+  generatedTsFolder: '/repo/package/temp/generated-typings',
+  fileExtensions: ['file-extension'],
+  parseAndGenerateTypings: (fileContents: string, filePath: string) => {
+    const parsedFile = parseFile(fileContents);
+    const typings: string = generateTypings(parsedFile);
+    return typings;
+  }
+});
+
+// To run once before a compilation:
+typingsGenerator.generateTypings();
+
+// To start a watcher:
+typingsGenerator.runWatcher();
+```
+
+## Options
+
+### `srcFolder = '...'`
+
+This property is used as the source root folder for discovery of files for which typings should be generated.
+
+### `generatedTsFolder = '...'`
+
+This property specifies the folder in which `.d.ts` files should be dropped. It is recommended
+that this be a folder parallel to the source folder, specified in addition to the source folder in the
+[`rootDirs` `tsconfig.json` option](https://www.typescriptlang.org/docs/handbook/compiler-options.html).
+**The folder specified by this option is emptied when the utility is invoked.**
+
+### `fileExtensions = [...]`
+
+This property enumerates the file extensions that should be handled.
+
+### `parseAndGenerateTypings = (fileContents: string, filePath: string) => string`
+
+This property is used to specify the function that should be called on every file for which typings
+are being generated. In watch mode, this is called on every file creation and file update. It should
+return TypeScript declarations for the file it is called with.
+
+### `terminal`
+
+Optionally provide a [Terminal](https://github.com/microsoft/rushstack/blob/master/libraries/node-core-library/src/Terminal/Terminal.ts)
+object for logging. If one isn't provided, logs will go to the terminal.
+
+### `filesToIgnore`
+
+Optionally, provide an array of paths to files that should be ignored. These paths can either be absolute
+paths, or paths relative to the [`srcFolder`](#srcFolder--)
+
+## `StringValuesTypingsGenerator`
+
+There is an extension of this utility specifically for file types where typings should be a simple
+set of exported string values. This is useful for file types like CSS and RESX. This class takes
+the same options as the standard `TypingsGenerator`, with one additional option ([`exportAsDefault`](#exportAsDefault--)) and a different return value for `parseAndGenerateTypings`.
+
+### `parseAndGenerateTypings = (fileContents: string, filePath: string) => { typings: ({ exportName: string, comment?: string })[] }`
+
+This function should behave the same as the `parseAndGenerateTypings` function for the standard
+`TypingsGenerator`, except that it should return an object with a `typings` property, set to
+an array of objects with an `exportName` property and an optional `comment` property.
+See the example below.
+
+#### Example return value:
+
+```TypeScript
+{
+  typings: [
+    {
+      exportName: 'myExport'
+    },
+    {
+      exportName: 'myOtherExport',
+      comment: 'This is the other export'
+    }
+  ]
+}
+```
+
+#### Example generated declaration file:
+
+```TypeScript
+// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export declare const myExport: string;
+
+/**
+ * This is the other export
+ */
+export declare const myOtherExport: string;
+
+```
+
+### `exportAsDefault = true | false`
+
+If this option is set to `true`, the typings will be exported wrapped in a `default` property. This
+allows the file to be imported by using the `import myFile from './myFile.my-extension';` syntax instead of
+the `import { myExport } from './myFile.my-extension';` or the `import * as myFile from './myFile.my-extension';`
+syntax. This style of export is not recommended as it can prevent tree-shaking optimization.
diff --git a/libraries/typings-generator/src/TypingsGenerator.ts b/libraries/typings-generator/src/TypingsGenerator.ts
@@ -18,8 +18,8 @@ import * as chokidar from 'chokidar';
  */
 export interface ITypingsGeneratorOptions<TTypingsResult = string> {
   srcFolder: string;
-  fileExtensions: string[];
   generatedTsFolder: string;
+  fileExtensions: string[];
   parseAndGenerateTypings: (fileContents: string, filePath: string) => TTypingsResult;
   terminal?: Terminal;
   filesToIgnore?: string[];
diff --git a/webpack/localization-plugin/README.md b/webpack/localization-plugin/README.md
@@ -227,7 +227,7 @@ This property is required if `typingsOptions` is set.
 This optional property overrides the compiler context for discovery of localization files for which
 typings should be generated.
 
-### `typingsOptions.exportAsDefault = true | false`
+#### `typingsOptions.exportAsDefault = true | false`
 
 If this option is set to `true`, loc modules typings will be exported wrapped in a `default` property. This
 allows strings to be imported by using the `import strings from './strings.loc.json';` syntax instead of
