{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-ast-js","path":"/generators/ast-js","type":"module","module":"generators-ast-js","title":"Parsing JavaScript","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `ast-js` stage parses the `.js` files among your inputs into syntax trees\nwith [Acorn](https://github.com/acornjs/acorn), for generators that read source\ncode rather than Markdown. [API links](https://doc-kit.nodejs.org/generators/api-links)\nis the built-in generator that reads it, and a\n[generator of your own](https://doc-kit.nodejs.org/creating-generators) can\ntoo. You don't ask for `ast-js` yourself: it runs when a target depends on it,\nonce per run however many targets read it.","summary":"The `ast-js` stage parses the `.js` files among your inputs into syntax trees with Acorn, for generators that read source code rather than Markdown. API links is the built-in generator that reads it, and a generator of your own can too. You don't ask for `ast-js` yourself: it runs when a target depends on it, once per run however many targets read it.","examples":[],"children":[{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`ast-js` has no options of its own. It parses the files `input` matches, minus\nthose `ignore` matches (see\n[Global options](https://doc-kit.nodejs.org/configuration#global-options)),\nand of those only the ones ending in `.js`.\n\nWhen the same run builds pages, keep `global.input` for your docs and give\n`ast-js` its own: the [Markdown stage](https://doc-kit.nodejs.org/generators/ast)\nparses every file `global.input` matches as Markdown, whatever its extension.\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  target: ['html', 'api-links'],\n  global: {\n    input: ['doc/api/*.md'],\n    output: 'out',\n  },\n  'ast-js': {\n    input: ['lib/*.js'],\n    ignore: ['lib/*.test.js'],\n  },\n};\n```\n\nFiles are parsed as scripts, so `import`, `export` and top-level `await` are\nsyntax errors, and a file that fails to parse stops the run. Leave ES modules\nout with `ignore`. Acorn doesn't parse JSX or type annotations either; to\ndocument TypeScript sources, see\n[Documenting TypeScript](https://doc-kit.nodejs.org/typescript).","summary":"`ast-js` has no options of its own. It parses the files `input` matches, minus those `ignore` matches (see Global options), and of those only the ones ending in `.js`.","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  target: ['html', 'api-links'],\n  global: {\n    input: ['doc/api/*.md'],\n    output: 'out',\n  },\n  'ast-js': {\n    input: ['lib/*.js'],\n    ignore: ['lib/*.test.js'],\n  },\n};"}],"children":[]},{"kind":"section","id":"what-it-produces","name":"What it produces","title":"What it produces","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"An array with one ESTree\n[`Program`](https://github.com/estree/estree/blob/master/es5.md#programs) node\nper file, as Acorn returns it with `locations` on, plus a `path` property: the\nfile's path as the glob matched it, such as `lib/fs.js`. Files are collected\nas their chunks finish, so the array isn't in input order. A generator with\n`dependsOn: '@doc-kit/core/ast-js'` receives this array.","summary":"An array with one ESTree `Program` node per file, as Acorn returns it with `locations` on, plus a `path` property: the file's path as the glob matched it, such as `lib/fs.js`. Files are collected as their chunks finish, so the array isn't in input order. A generator with `dependsOn: '@doc-kit/core/ast-js'` receives this array.","examples":[],"children":[]}]}