{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-addon-verify","path":"/generators/addon-verify","type":"module","module":"generators-addon-verify","title":"Addon examples","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `addon-verify` generator pulls the C++ addon examples out of an addons\ndocument, such as Node.js's `doc/api/addons.md`, and writes each one to its own\nfolder with a `binding.gyp`, so a test suite can compile and run the examples\nyour docs show.\n\n**Target:** `addon-verify` · **Package:** [`@node-core/doc-kit`](https://doc-kit.nodejs.org/packages/node) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** a folder per example, such as `02_function_arguments/`","summary":"The `addon-verify` generator pulls the C++ addon examples out of an addons document, such as Node.js's `doc/api/addons.md`, and writes each one to its own folder with a `binding.gyp`, so a test suite can compile and run the examples your docs show.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"From the root of a Node.js checkout:\n\n```bash\nnpm install --save-dev @doc-kit/cli @node-core/doc-kit\nnpx doc-kit generate -t addon-verify -i doc/api/addons.md -o test/addons\n```\n\nThis writes one folder per example to `test/addons/`. Building and running\nthem is up to your test suite.","summary":"From the root of a Node.js checkout:","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @node-core/doc-kit\nnpx doc-kit generate -t addon-verify -i doc/api/addons.md -o test/addons"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`addon-verify` has no options of its own. It reads this global option, which\nyou can also set in an `addon-verify` section to apply to it alone:\n\n* `output` {string} The directory to write the example folders to. Without\n  one, nothing is written. **Default:** from `global.output` (`--output`).","summary":"`addon-verify` has no options of its own. It reads this global option, which you can also set in an `addon-verify` section to apply to it alone:","examples":[],"children":[]},{"kind":"section","id":"marking-up-an-example","name":"Marking up an example","title":"Marking up an example","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Each heading's section, its content up to the next heading of any level, is a\npossible example. In it, the generator picks the code blocks whose first line\nis a `//` comment naming a `.cc`, `.h` or `.js` file:\n\n````md displayName=\"doc/api/addons.md\"\n### Function arguments\n\n```cpp\n// addon.cc\n#include <node.h>\n```\n\n```js\n// test.js\nconst addon = require('./build/Release/addon');\n\nconsole.log('This should be eight:', addon.add(3, 5));\n```\n````\n\n* The first line must be `//`, one or more spaces, and the file name, with\n  nothing after it. `//addon.cc`, `// addon.cc (C++)`, and `.cpp` or `.hpp`\n  files are skipped without a warning.\n* The comment sets the file name and stays in the written file. The code\n  block's language doesn't matter.\n* Code blocks without such a comment, like a `bash` block with build commands,\n  are ignored.\n* A section becomes an example only when it has at least one `.cc` file and\n  one `.js` file.\n\n> \\[!IMPORTANT]\n> Keep all of an example's files under one heading. A code block under a\n> nested heading belongs to that heading's section, so a `.js` file under a\n> `### Building` subheading doesn't join the `.cc` file above it. Two headings\n> with the same text, on the other hand, share one folder with the files of\n> both.","summary":"Each heading's section, its content up to the next heading of any level, is a possible example. In it, the generator picks the code blocks whose first line is a `//` comment naming a `.cc`, `.h` or `.js` file:","examples":[{"language":"md","displayName":"doc/api/addons.md","code":"### Function arguments\n\n```cpp\n// addon.cc\n#include <node.h>\n```\n\n```js\n// test.js\nconst addon = require('./build/Release/addon');\n\nconsole.log('This should be eight:', addon.add(3, 5));\n```"}],"children":[]},{"kind":"section","id":"output-layout","name":"Output layout","title":"Output layout","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"For Node.js's `doc/api/addons.md`, the run above writes:\n\n```text\ntest/addons/\n├── 01_worker_support/\n│   ├── addon.cc\n│   ├── binding.gyp\n│   └── test.js\n├── 02_function_arguments/\n│   ├── addon.cc\n│   ├── binding.gyp\n│   └── test.js\n├── …\n└── 08_passing_wrapped_objects_around/\n    ├── addon.cc\n    ├── binding.gyp\n    ├── myobject.cc\n    ├── myobject.h\n    └── test.js\n```\n\nEach folder is named after its heading: a two-digit number, counting from `01`\nthe sections that became examples in the order they appear, then the heading\nin lowercase, with spaces turned into underscores and other punctuation\nremoved. \"Wrapping C++ objects\" becomes `06_wrapping_c_objects`.\n\nEvery file is written as its code block holds it, except `test.js`, which is\nprepared for Node.js's test suite: two lines are added at the top, and the\nfirst `'./build/Release/addon'` is replaced with a path built from\n`common.buildType`, so the test finds the addon in Debug builds too:\n\n```js displayName=\"test/addons/02_function_arguments/test.js\"\n'use strict';\nconst common = require('../../common');\n// test.js\nconst addon = require(`./build/${common.buildType}/addon`);\n\nconsole.log('This should be eight:', addon.add(3, 5));\n```\n\n> \\[!WARNING]\n> The generator also changes the indentation and escapes of `test.js`. It\n> removes the smallest indentation it finds, up to four spaces, from every\n> indented line, so nested code shifts left and the added lines can end up\n> indented. Escape sequences turn into the characters they stand for: a `\\n`\n> inside a quoted string becomes a real line break, which is a syntax error.\n> Check the written `test.js` when your example has nested blocks or escapes.\n\nNext to the files, the generator writes a `binding.gyp`, on a single line,\nwith one target named `addon` that lists every file of the example as a\nsource, in order, and includes `../common.gypi`. Indented:\n\n```json displayName=\"test/addons/02_function_arguments/binding.gyp\"\n{\n  \"targets\": [\n    {\n      \"target_name\": \"addon\",\n      \"sources\": [\"addon.cc\", \"test.js\"],\n      \"includes\": [\"../common.gypi\"]\n    }\n  ]\n}\n```\n\n`../../common` and `../common.gypi` resolve to `test/common` and\n`test/addons/common.gypi` when the output is `test/addons` in a Node.js\ncheckout. To use the examples anywhere else, put a `common.gypi` in the output\ndirectory, and a `common` module that exports `buildType` (such as\n`'Release'`) in its parent.\n\n> \\[!NOTE]\n> The generator doesn't remove folders from earlier runs. When an example is\n> removed, renamed or moved, delete the old numbered folders before you\n> regenerate, for example with `rm -rf test/addons/??_*/`.","summary":"For Node.js's `doc/api/addons.md`, the run above writes:","examples":[{"language":"text","displayName":null,"code":"test/addons/\n├── 01_worker_support/\n│   ├── addon.cc\n│   ├── binding.gyp\n│   └── test.js\n├── 02_function_arguments/\n│   ├── addon.cc\n│   ├── binding.gyp\n│   └── test.js\n├── …\n└── 08_passing_wrapped_objects_around/\n    ├── addon.cc\n    ├── binding.gyp\n    ├── myobject.cc\n    ├── myobject.h\n    └── test.js"},{"language":"js","displayName":"test/addons/02_function_arguments/test.js","code":"'use strict';\nconst common = require('../../common');\n// test.js\nconst addon = require(`./build/${common.buildType}/addon`);\n\nconsole.log('This should be eight:', addon.add(3, 5));"},{"language":"json","displayName":"test/addons/02_function_arguments/binding.gyp","code":"{\n  \"targets\": [\n    {\n      \"target_name\": \"addon\",\n      \"sources\": [\"addon.cc\", \"test.js\"],\n      \"includes\": [\"../common.gypi\"]\n    }\n  ]\n}"}],"children":[]}]}