|
| 1 | +# @microsoft/tsdoc-config |
| 2 | + |
| 3 | +**TSDoc** is a proposal to standardize the doc comments used in [TypeScript](http://www.typescriptlang.org/) |
| 4 | +source files. The main package [`@microsoft/tsdoc`](https://www.npmjs.com/package/@microsoft/tsdoc) implements |
| 5 | +the TSDoc parser. The `@microsoft/tsdoc-config` package is an optional add-on for loading the **tsdocconfig.json** |
| 6 | +file format that enables users to define custom TSDoc tags. (This functionality was moved to its own package |
| 7 | +because it requires external dependencies such as NodeJS and `ajv`, whereas the main package is fully self-contained.) |
| 8 | + |
| 9 | +For more information about TSDoc, please visit the project website: |
| 10 | + |
| 11 | +https://github.com/microsoft/tsdoc |
| 12 | + |
| 13 | + |
| 14 | +## Creating config files |
| 15 | + |
| 16 | +The **tsdocconfig.json** file is optional. When used, it is expected to be found in the same folder as |
| 17 | +the **tsconfig.json** file for a project. The loader looks for it by walking upwards in the directory tree |
| 18 | +from until it finds a folder containing **tsconfig.json** or **package.json**, and then it attempts to load |
| 19 | +**tsdocconfig.json** from that location. |
| 20 | + |
| 21 | +The **tsdocconfig.json** file conforms to the [tsdocconfig.schema.json]( |
| 22 | +https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json) JSON schema. It defines tags using |
| 23 | +similar fields as the |
| 24 | +[TSDocTagDefinition](https://github.com/microsoft/tsdoc/blob/master/tsdoc/src/configuration/TSDocTagDefinition.ts) |
| 25 | +API used by `TSDocParser` from `@microsoft/tsdoc`. |
| 26 | + |
| 27 | +Here's a simple example: |
| 28 | + |
| 29 | +**tsdocconfig.json** |
| 30 | +```js |
| 31 | +{ |
| 32 | + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", |
| 33 | + "tagDefinitions": [ |
| 34 | + { |
| 35 | + "tagName": "@myTag", |
| 36 | + "syntaxKind": "modifier" |
| 37 | + } |
| 38 | + ] |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +If you want to define custom tags in one place and share them across multiple projects, the `extends` field specifies |
| 43 | +a list of paths that will be mixed in with the current file: |
| 44 | + |
| 45 | +**tsdocconfig.json** |
| 46 | +```js |
| 47 | +{ |
| 48 | + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v1/tsdocconfig.schema.json", |
| 49 | + "extends": [ |
| 50 | + "my-package/dist/tsdocconfig-base.json", |
| 51 | + "./path/to/local/file/tsdocconfig-local.json" |
| 52 | + ] |
| 53 | +} |
| 54 | +``` |
| 55 | + |
| 56 | +> NOTE: The `extends` paths are resolved using NodeJS module resolution, so local paths must being with `./` to avoid |
| 57 | +> being interpreted as an NPM package name. |
| 58 | +
|
| 59 | + |
| 60 | +## API Usage |
| 61 | + |
| 62 | +The code sample below illustrates how to invoke the `@microsoft/tsdoc-config` API to load a |
| 63 | +**tsdocconfig.json** file: |
| 64 | + |
| 65 | +```ts |
| 66 | +import * as path from 'path'; |
| 67 | +import { TSDocParser, TSDocConfiguration } from '@microsoft/tsdoc'; |
| 68 | +import { TSDocConfigFile } from '@microsoft/tsdoc-config'; |
| 69 | + |
| 70 | +// Sample source file to be parsed |
| 71 | +const mySourceFile: string = 'my-project/src/example.ts'; |
| 72 | + |
| 73 | +// Load the nearest config file, for example `my-project/tsdocconfig.json` |
| 74 | +const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.dirname(mySourceFile)); |
| 75 | +if (tsdocConfigFile.hasErrors) { |
| 76 | + // Report any errors |
| 77 | + console.log(tsdocConfigFile.getErrorSummary()); |
| 78 | +} |
| 79 | + |
| 80 | +// Use the TSDocConfigFile to configure the parser |
| 81 | +const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration(); |
| 82 | +tsdocConfigFile.configureParser(tsdocConfiguration); |
| 83 | +const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration); |
| 84 | +``` |
| 85 | + |
0 commit comments