diff --git a/docs/manifest.json b/docs/manifest.json index c6eccbce1d73d3..fbaa1039cf678d 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -635,6 +635,12 @@ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/deprecated/README.md", "parent": "packages" }, + { + "title": "@wordpress/docgen", + "slug": "packages-docgen", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/docgen/README.md", + "parent": "packages" + }, { "title": "@wordpress/dom-ready", "slug": "packages-dom-ready", diff --git a/package-lock.json b/package-lock.json index 1b825c2ffbb3a4..2f0d39cd7a38c8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2701,6 +2701,17 @@ "@wordpress/hooks": "file:packages/hooks" } }, + "@wordpress/docgen": { + "version": "file:packages/docgen", + "dev": true, + "requires": { + "mdast-util-inject": "1.1.0", + "optionator": "0.8.2", + "remark": "10.0.1", + "remark-parse": "6.0.3", + "unified": "7.1.0" + } + }, "@wordpress/dom": { "version": "file:packages/dom", "requires": { @@ -13865,6 +13876,21 @@ "unist-util-visit": "^1.1.0" } }, + "mdast-util-inject": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/mdast-util-inject/-/mdast-util-inject-1.1.0.tgz", + "integrity": "sha1-2wa4tYW+lZotzS+H9HK6m3VvNnU=", + "dev": true, + "requires": { + "mdast-util-to-string": "^1.0.0" + } + }, + "mdast-util-to-string": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-1.0.5.tgz", + "integrity": "sha512-2qLt/DEOo5F6nc2VFScQiHPzQ0XXcabquRJxKMhKte8nt42o08HUxNDPk7tt0YPxnWjAT11I1SYi0X0iPnfI5A==", + "dev": true + }, "mdn-data": { "version": "1.1.4", "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-1.1.4.tgz", diff --git a/package.json b/package.json index eb1b308d87f2a1..b0965325aa435e 100644 --- a/package.json +++ b/package.json @@ -66,6 +66,7 @@ "@wordpress/babel-preset-default": "file:packages/babel-preset-default", "@wordpress/browserslist-config": "file:packages/browserslist-config", "@wordpress/custom-templated-path-webpack-plugin": "file:packages/custom-templated-path-webpack-plugin", + "@wordpress/docgen": "file:packages/docgen", "@wordpress/e2e-test-utils": "file:packages/e2e-test-utils", "@wordpress/e2e-tests": "file:packages/e2e-tests", "@wordpress/eslint-plugin": "file:packages/eslint-plugin", @@ -161,6 +162,7 @@ "dev": "npm run build:packages && concurrently \"wp-scripts start\" \"npm run dev:packages\"", "dev:packages": "node ./bin/packages/watch.js", "docs:build": "node docs/tool", + "docs:generate": "lerna run docs:generate", "fixtures:clean": "rimraf \"packages/e2e-tests/fixtures/blocks/*.+(json|serialized.html)\"", "fixtures:server-registered": "docker-compose run -w /var/www/html/wp-content/plugins/gutenberg --rm wordpress ./bin/get-server-blocks.php > test/integration/full-content/server-registered.json", "fixtures:generate": "npm run fixtures:server-registered && cross-env GENERATE_MISSING_FIXTURES=y npm run test-unit", diff --git a/packages/docgen/.npmrc b/packages/docgen/.npmrc new file mode 100644 index 00000000000000..43c97e719a5a82 --- /dev/null +++ b/packages/docgen/.npmrc @@ -0,0 +1 @@ +package-lock=false diff --git a/packages/docgen/CHANGELOG.md b/packages/docgen/CHANGELOG.md new file mode 100644 index 00000000000000..ae69187866b19e --- /dev/null +++ b/packages/docgen/CHANGELOG.md @@ -0,0 +1,3 @@ +## 1.0.0 (Unreleased) + +- Initial release diff --git a/packages/docgen/README.md b/packages/docgen/README.md new file mode 100644 index 00000000000000..c62b96fc4e44b4 --- /dev/null +++ b/packages/docgen/README.md @@ -0,0 +1,250 @@ +# `docgen` + +`docgen` helps you to generate the _public API_ of your code. Given an entry point file, it outputs the ES6 export statements and their corresponding JSDoc comments in human-readable format. + +Some characteristics: + +* If the export statement doesn't contain any JSDoc, it'll look up for JSDoc up to the declaration. +* It can resolve relative dependencies, either files or directories. For example, `import default from './dependency'` will find `dependency.js` or `dependency/index.js` + +## Installation + +Install the module + +```bash +npm install @wordpress/docgen --save-dev +``` + +## Usage + +```bash +npx docgen +``` + +This command will generate a file named `entry-point-api.md` containing all the exports and their JSDoc comments. + +### CLI options + +* **--formatter** `(String)`: A path to a custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input: + * *rootDir* `(String)`: current working directory as seen by docgen. + * *docPath* `(String)`: path of the output document to generate. + * *symbols* `(Array)`: the symbols found. +* **--ignore** `(RegExp)`: A regular expression used to ignore symbols whose name match it. +* **--output** `(String)`: Output file that will contain the API documentation. +* **--to-section** `(String)`: Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter. Depends on `--output` and bypasses the custom `--formatter` passed, if any. +* **--to-token**: Embed generated documentation within the start and end tokens in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any. + * Start token: `` + * End token: `` +* **--use-token** `(String)`: This options allows you to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token `` and the end token ``. Depends on `--to-token`. +* **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging. + +## Examples + +### Default export + +Entry point `index.js`: + +```js +/** + * Adds two numbers. + * + * @param {number} term1 First number. + * @param {number} term2 Second number. + * @return {number} The result of adding the two numbers. + */ +export default function addition( term1, term2 ) { + // Implementation would go here. +} +``` + +Output of `npx docgen index.js` would be `index-api.js`: + +```markdown +# API + +## default + +[example.js#L8-L10](example.js#L8-L10) + +Adds two numbers. + +**Parameters** + +- **term1** `number`: First number. +- **term2** `number`: Second number. + +**Returns** + +`number` The result of adding the two numbers. +``` + +### Named export + +Entry point `index.js`: + +```js +/** + * Adds two numbers. + * + * @param {number} term1 First number. + * @param {number} term2 Second number. + * @return {number} The result of adding the two numbers. + */ +function addition( term1, term2 ) { + return term1 + term2; +} + +/** + * Adds two numbers. + * + * @deprecated Use `addition` instead. + * + * @param {number} term1 First number. + * @param {number} term2 Second number. + * @return {number} The result of adding the two numbers. + */ +function count( term1, term2 ) { + return term1 + term2; +} + +export { count, addition }; +``` + +Output of `npx docgen index.js` would be `index-api.js`: + +```markdown +# API + +## addition + +[example.js#L25-L25](example.js#L25-L25) + +Adds two numbers. + +**Parameters** + +- **term1** `number`: First number. +- **term2** `number`: Second number. + +**Returns** + +`number` The result of adding the two numbers. + +## count + +[example.js#L25-L25](example.js#L25-L25) + +> **Deprecated** Use `addition` instead. + +Adds two numbers. + +**Parameters** + +- **term1** `number`: First number. +- **term2** `number`: Second number. + +**Returns** + +`number` The result of adding the two numbers. +``` + +### Namespace export + +Let the entry point be `index.js`: + +```js +export * from './count'; +``` + +with `./count/index.js` contents being: + +```js +/** + * Substracts two numbers. + * + * @example + * + * ```js + * const result = substraction( 5, 2 ); + * console.log( result ); // Will log 3 + * ``` + * + * @param {number} term1 First number. + * @param {number} term2 Second number. + * @return {number} The result of subtracting the two numbers. + */ +export function substraction( term1, term2 ) { + return term1 - term2; +} + +/** + * Adds two numbers. + * + * @example + * + * ```js + * const result = addition( 5, 2 ); + * console.log( result ); // Will log 7 + * ``` + * + * @param {number} term1 First number. + * @param {number} term2 Second number. + * @return {number} The result of adding the two numbers. + */ +export function addition( term1, term2 ) { + // Implementation would go here. + return term1 - term2; +} +``` + +Output of `npx docgen index.js` would be `index-api.js`: + +````markdown +# API + +## addition + +[example-module.js#L1-L1](example-module.js#L1-L1) + +Adds two numbers. + +**Usage** + +```js +const result = addition( 5, 2 ); +console.log( result ); // Will log 7 +``` + +**Parameters** + +- **term1** `number`: First number. +- **term2** `number`: Second number. + +**Returns** + +`number` The result of adding the two numbers. + +## substraction + +[example-module.js#L1-L1](example-module.js#L1-L1) + +Substracts two numbers. + +**Usage** + +```js +const result = substraction( 5, 2 ); +console.log( result ); // Will log 3 +``` + +**Parameters** + +- **term1** `number`: First number. +- **term2** `number`: Second number. + +**Returns** + +`number` The result of subtracting the two numbers. +```` + +

Code is Poetry.

diff --git a/packages/docgen/bin/cli.js b/packages/docgen/bin/cli.js new file mode 100755 index 00000000000000..bcc1a6f1e245d0 --- /dev/null +++ b/packages/docgen/bin/cli.js @@ -0,0 +1,44 @@ +#!/usr/bin/env node + +const docgen = require( '../src' ); + +const optionator = require( 'optionator' )( { + prepend: 'Usage: node ', + options: [ { + option: 'formatter', + type: 'String', + description: 'A custom function to format the generated documentation. By default, a Markdown formatter will be used.', + }, { + option: 'output', + type: 'String', + description: 'Output file to contain the API documentation.', + }, { + option: 'ignore', + type: 'RegExp', + description: 'A regular expression used to ignore symbols whose name match it.', + }, { + option: 'to-section', + type: 'String', + description: 'Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter.', + dependsOn: 'output', + }, { + option: 'to-token', + type: 'Boolean', + description: 'Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.', + dependsOn: 'output', + }, { + option: 'use-token', + type: 'String', + default: 'Autogenerated API docs', + description: 'Add this string to the start/end tokens.', + dependsOn: 'to-token', + }, { + option: 'debug', + type: 'Boolean', + default: false, + description: 'Run in debug mode, which outputs some intermediate files useful for debugging.', + } ], +} ); + +const options = optionator.parseArgv( process.argv ); +docgen( options._[ 0 ], options ); diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md new file mode 100644 index 00000000000000..83c5dfd3d59fa6 --- /dev/null +++ b/packages/docgen/coverage.md @@ -0,0 +1,83 @@ +# Coverage + +## Packages outside of scope + +- babel-plugin-makepot. CommonJS module. Babel plugin. +- babel-preset-default. CommonJS module. Babel preset. +- browserslist-config. CommonJS module. Config. +- custom-templated-path-webpack-plugin. CommonJS module. Webpack plugin. +- docgen. CommonJS module. +- e2e-tests. Do not export anything. +- eslint-plugin. CommonJS module. ESLint plugin. +- is-shallow-equal. CommonJS module. +- jest-preset-default. CommonJS module. Jest preset. +- library-export-default-webpack-plugin. CommonJS. Webpack plugin. +- npm-package-json-lint-config. CommonJS. Config. +- postcss-themes. CommonJS module. +- scripts. CommonJS module. + +## TODO + +These either happen in private API, aren't relevant, or are pending of decission. + +- [ ] go undocummented: `unstable__*`, rich-text `unstableToDom`, `experimental__` +- [ ] `constants` keycodes, rich-text `LINE_SEPARATOR` +- [ ] `{?{ time: number, count: number }}`packages/editor/src/store/selectors.js +- [ ] `{type=}` packages/block-library/src/image/edit.js +- [ ] `@api` packages/editor/src/editor-styles/ast/stringify/compiler.js +- [ ] `@callback` packages/components/src/autocomplete/index.js +- [ ] `@cite` packages/block-serialization-default-parser/src/index.js +- [ ] `@class` packages/edit-post/src/hooks/components/media-upload/index.js +- [ ] `@const` packages/editor/src/editor-styles/transforms/wrap.js +- [ ] `@constant` packages/editor/src/hooks/align.js +- [ ] `@constructor` packages/edit-post/src/hooks/components/media-upload/index.js +- [ ] `@inheritdoc` packages/edit-post/src/components/meta-boxes/meta-boxes-area/index.js +- [ ] `@private` packages/editor/src/components/rich-text/index.js +- [ ] `@property` babel-plugin-import-jsx-pragma +- [ ] `@since` packages/block-serialization-default-parser/src/index.js +- [ ] `@throws` packages/blocks/src/api/node.js +- [ ] `@typedef` packages/blocks/src/api/registration.js + +## DONE + +- [x] a11y +- [x] annotations +- [x] api-fetch +- [x] babel-plugin-import-jsx-pragma +- [x] blob +- [x] block-library +- [x] block-serialization-default-parser +- [x] block-serialization-spec-parser +- [x] blocks +- [x] components +- [x] compose +- [x] core-data +- [x] data +- [x] date +- [x] deprecated +- [x] dom +- [x] dom-ready +- [x] e2e-test-utils +- [x] edit-post +- [x] editor +- [x] element +- [x] escape-html +- [x] format-library +- [x] hooks +- [x] html-entities +- [x] i18n +- [x] jest-console +- [x] jest-puppeteer-axe +- [x] keycodes +- [x] list-reusable-blocks +- [x] notices +- [x] nux +- [x] plugins +- [x] priority-queue +- [x] redux-routine +- [x] rich-text +- [x] shortcode +- [x] token-list +- [x] url +- [x] viewport +- [x] wordcount diff --git a/packages/docgen/package.json b/packages/docgen/package.json new file mode 100644 index 00000000000000..a73ed098f3142b --- /dev/null +++ b/packages/docgen/package.json @@ -0,0 +1,33 @@ +{ + "name": "@wordpress/docgen", + "version": "1.0.0-beta.0", + "description": "Autogenerate public API documentation from exports and JSDoc comments.", + "author": "The WordPress Contributors", + "license": "GPL-2.0-or-later", + "keywords": [ + "jsdoc", + "documentation", + "wordpress" + ], + "homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/docgen/README.md", + "repository": { + "type": "git", + "url": "git+https://github.com/WordPress/gutenberg.git" + }, + "bugs": { + "url": "https://github.com/WordPress/gutenberg/issues" + }, + "bin": { + "docgen": "./bin/cli.js" + }, + "dependencies": { + "mdast-util-inject": "1.1.0", + "optionator": "0.8.2", + "remark": "10.0.1", + "remark-parse": "6.0.3", + "unified": "7.1.0" + }, + "publishConfig": { + "access": "public" + } +} diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js new file mode 100644 index 00000000000000..0c01f94ef9b505 --- /dev/null +++ b/packages/docgen/src/engine.js @@ -0,0 +1,56 @@ +/** +* External dependencies. +*/ +const espree = require( 'espree' ); +const { flatten } = require( 'lodash' ); + +/** +* Internal dependencies. +*/ +const getIntermediateRepresentation = require( './get-intermediate-representation' ); + +const getAST = ( source ) => espree.parse( source, { + attachComment: true, + loc: true, + ecmaVersion: 2018, + ecmaFeatures: { + jsx: true, + }, + sourceType: 'module', +} ); + +const getExportTokens = ( ast ) => ast.body.filter( + ( node ) => [ + 'ExportNamedDeclaration', + 'ExportDefaultDeclaration', + 'ExportAllDeclaration', + ].some( ( declaration ) => declaration === node.type ) +); + +const engine = ( path, code, getIRFromPath = () => {} ) => { + const result = {}; + result.ast = getAST( code ); + result.tokens = getExportTokens( result.ast ); + result.ir = flatten( result.tokens.map( + ( token ) => getIntermediateRepresentation( + path, + token, + result.ast, + getIRFromPath + ) + ) ); + + return result; +}; + +/** + * Function that takes code and returns an intermediate representation. + * + * @param {string} code The code to parse. + * @param {Function} [getIRFromPath=noop] Callback to retrieve the + * Intermediate Representation from a path relative to the file + * being parsed. + * + * @return {Object} Intermediate Representation in JSON. + */ +module.exports = engine; diff --git a/packages/docgen/src/get-dependency-path.js b/packages/docgen/src/get-dependency-path.js new file mode 100644 index 00000000000000..83c043023ed441 --- /dev/null +++ b/packages/docgen/src/get-dependency-path.js @@ -0,0 +1,3 @@ +module.exports = function( token ) { + return token.source.value; +}; diff --git a/packages/docgen/src/get-export-entries.js b/packages/docgen/src/get-export-entries.js new file mode 100644 index 00000000000000..a69811b2b6545d --- /dev/null +++ b/packages/docgen/src/get-export-entries.js @@ -0,0 +1,97 @@ +/** + * External dependencies + */ +const { get } = require( 'lodash' ); + +/** + * Returns the export entry records of the given export statement. + * Unlike [the standard](http://www.ecma-international.org/ecma-262/9.0/#exportentry-record), + * the `importName` and the `localName` are merged together. + * + * @param {Object} token Espree node representing an export. + * + * @return {Array} Exported entry records. Example: + * [ { + * localName: 'localName', + * exportName: 'exportedName', + * module: null, + * lineStart: 2, + * lineEnd: 3, + * } ] + */ +module.exports = function( token ) { + if ( token.type === 'ExportDefaultDeclaration' ) { + const getLocalName = ( t ) => { + let name; + switch ( t.declaration.type ) { + case 'Identifier': + name = t.declaration.name; + break; + case 'AssignmentExpression': + name = t.declaration.left.name; + break; + //case 'FunctionDeclaration' + //case 'ClassDeclaration' + default: + name = get( t.declaration, [ 'id', 'name' ], '*default*' ); + } + return name; + }; + return [ { + localName: getLocalName( token ), + exportName: 'default', + module: null, + lineStart: token.loc.start.line, + lineEnd: token.loc.end.line, + } ]; + } + + if ( token.type === 'ExportAllDeclaration' ) { + return [ { + localName: '*', + exportName: null, + module: token.source.value, + lineStart: token.loc.start.line, + lineEnd: token.loc.end.line, + } ]; + } + + const name = []; + if ( token.declaration === null ) { + token.specifiers.forEach( ( specifier ) => name.push( { + localName: specifier.local.name, + exportName: specifier.exported.name, + module: get( token.source, [ 'value' ], null ), + lineStart: specifier.loc.start.line, + lineEnd: specifier.loc.end.line, + } ) ); + return name; + } + + switch ( token.declaration.type ) { + case 'ClassDeclaration': + case 'FunctionDeclaration': + name.push( { + localName: token.declaration.id.name, + exportName: token.declaration.id.name, + module: null, + lineStart: token.declaration.loc.start.line, + lineEnd: token.declaration.loc.end.line, + } ); + break; + + case 'VariableDeclaration': + token.declaration.declarations.forEach( ( declaration ) => { + name.push( { + localName: declaration.id.name, + exportName: declaration.id.name, + module: null, + lineStart: token.declaration.loc.start.line, + lineEnd: token.declaration.loc.end.line, + } ); + } ); + break; + } + + return name; +}; diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js new file mode 100644 index 00000000000000..eee7775d69979a --- /dev/null +++ b/packages/docgen/src/get-intermediate-representation.js @@ -0,0 +1,152 @@ +/** + * External dependencies. + */ +const { get } = require( 'lodash' ); + +/** + * Internal dependencies. + */ +const getExportEntries = require( './get-export-entries' ); +const getJSDocFromToken = require( './get-jsdoc-from-token' ); +const getDependencyPath = require( './get-dependency-path' ); + +const UNDOCUMENTED = 'Undocumented declaration.'; +const NAMESPACE_EXPORT = '*'; +const DEFAULT_EXPORT = 'default'; + +const hasClassWithName = ( node, name ) => + node.type === 'ClassDeclaration' && + node.id.name === name; + +const hasFunctionWithName = ( node, name ) => + node.type === 'FunctionDeclaration' && + node.id.name === name; + +const hasVariableWithName = ( node, name ) => + node.type === 'VariableDeclaration' && + node.declarations.some( ( declaration ) => { + if ( declaration.id.type === 'ObjectPattern' ) { + return declaration.id.properties.some( + ( property ) => property.key.name === name + ); + } + return declaration.id.name === name; + } ); + +const hasNamedExportWithName = ( node, name ) => + node.type === 'ExportNamedDeclaration' && ( + ( node.declaration && hasClassWithName( node.declaration, name ) ) || + ( node.declaration && hasFunctionWithName( node.declaration, name ) ) || + ( node.declaration && hasVariableWithName( node.declaration, name ) ) + ); + +const hasImportWithName = ( node, name ) => + node.type === 'ImportDeclaration' && + node.specifiers.some( ( specifier ) => specifier.local.name === name ); + +const isImportDeclaration = ( node ) => node.type === 'ImportDeclaration'; + +const someImportMatchesName = ( name, token ) => { + let matches = false; + token.specifiers.forEach( ( specifier ) => { + if ( ( specifier.type === 'ImportDefaultSpecifier' ) && ( name === 'default' ) ) { + matches = true; + } + if ( ( specifier.type === 'ImportSpecifier' ) && ( name === specifier.imported.name ) ) { + matches = true; + } + } ); + return matches; +}; + +const someEntryMatchesName = ( name, entry, token ) => + ( token.type === 'ExportNamedDeclaration' && entry.localName === name ) || + ( token.type === 'ImportDeclaration' && someImportMatchesName( name, token ) ); + +const getJSDocFromDependency = ( token, entry, parseDependency ) => { + let doc; + const ir = parseDependency( getDependencyPath( token ) ); + if ( entry.localName === NAMESPACE_EXPORT ) { + doc = ir.filter( ( { name } ) => name !== DEFAULT_EXPORT ); + } else { + doc = ir.find( ( { name } ) => someEntryMatchesName( name, entry, token ) ); + } + return doc; +}; + +const getJSDoc = ( token, entry, ast, parseDependency ) => { + let doc; + if ( entry.localName !== NAMESPACE_EXPORT ) { + doc = getJSDocFromToken( token ); + if ( ( doc !== undefined ) ) { + return doc; + } + } + + if ( entry && entry.module === null ) { + const candidates = ast.body.filter( ( node ) => { + return hasClassWithName( node, entry.localName ) || + hasFunctionWithName( node, entry.localName ) || + hasVariableWithName( node, entry.localName ) || + hasNamedExportWithName( node, entry.localName ) || + hasImportWithName( node, entry.localName ); + } ); + if ( candidates.length !== 1 ) { + return doc; + } + const node = candidates[ 0 ]; + if ( isImportDeclaration( node ) ) { + doc = getJSDocFromDependency( node, entry, parseDependency ); + } else { + doc = getJSDocFromToken( node ); + } + return doc; + } + + return getJSDocFromDependency( token, entry, parseDependency ); +}; + +/** + * Takes a export token and returns an intermediate representation in JSON. + * + * If the export token doesn't contain any JSDoc, and it's a identifier, + * the identifier declaration will be looked up in the file or dependency + * if an `ast` and `parseDependency` callback are provided. + * + * @param {string} path Path to file being processed. + * @param {Object} token Espree export token. + * @param {Object} [ast] Espree ast of the file being parsed. + * @param {Function} [parseDependency] Function that takes a path + * and returns the intermediate representation of the dependency file. + * + * @return {Object} Intermediate Representation in JSON. + */ +module.exports = function( path, token, ast = { body: [] }, parseDependency = () => {} ) { + const exportEntries = getExportEntries( token ); + const ir = []; + exportEntries.forEach( ( entry ) => { + const doc = getJSDoc( token, entry, ast, parseDependency ); + if ( entry.localName === NAMESPACE_EXPORT ) { + doc.forEach( ( namedExport ) => { + ir.push( { + path, + name: namedExport.name, + description: namedExport.description, + tags: namedExport.tags, + lineStart: entry.lineStart, + lineEnd: entry.lineEnd, + } ); + } ); + } else { + ir.push( { + path, + name: entry.exportName, + description: get( doc, [ 'description' ], UNDOCUMENTED ), + tags: get( doc, [ 'tags' ], [] ), + lineStart: entry.lineStart, + lineEnd: entry.lineEnd, + } ); + } + } ); + return ir; +}; diff --git a/packages/docgen/src/get-jsdoc-from-token.js b/packages/docgen/src/get-jsdoc-from-token.js new file mode 100644 index 00000000000000..e888abc53d06ca --- /dev/null +++ b/packages/docgen/src/get-jsdoc-from-token.js @@ -0,0 +1,37 @@ +/** + * External dependencies. + */ +const doctrine = require( 'doctrine' ); + +/** + * Internal dependencies. + */ +const getLeadingComments = require( './get-leading-comments' ); +const getTypeAsString = require( './get-type-as-string' ); + +/** + * Function that takes an Espree token and returns + * a object representing the leading JSDoc comment of the token, + * if any. + * + * @param {Object} token Espree token. + * @return {Object} Object representing the JSDoc comment. + */ +module.exports = function( token ) { + let jsdoc; + const comments = getLeadingComments( token ); + if ( comments && comments.startsWith( '*\n' ) ) { + jsdoc = doctrine.parse( comments, { + unwrap: true, + recoverable: true, + sloppy: true, + } ); + jsdoc.tags = jsdoc.tags.map( ( tag ) => { + if ( tag.type ) { + tag.type = getTypeAsString( tag.type ); + } + return tag; + } ); + } + return jsdoc; +}; diff --git a/packages/docgen/src/get-leading-comments.js b/packages/docgen/src/get-leading-comments.js new file mode 100644 index 00000000000000..3f025278b10337 --- /dev/null +++ b/packages/docgen/src/get-leading-comments.js @@ -0,0 +1,20 @@ +/** + * External dependencies. + */ +const { last } = require( 'lodash' ); + +/** + * Function that returns the leading comment + * of a Espree node. + * + * @param {Object} declaration Espree node to inspect + * + * @return {?string} Leading comment or undefined if there is none. + */ +module.exports = function( declaration ) { + let comments; + if ( declaration.leadingComments ) { + comments = last( declaration.leadingComments ).value; + } + return comments; +}; diff --git a/packages/docgen/src/get-type-as-string.js b/packages/docgen/src/get-type-as-string.js new file mode 100644 index 00000000000000..64bfaefd00d529 --- /dev/null +++ b/packages/docgen/src/get-type-as-string.js @@ -0,0 +1,44 @@ +const maybeAddDefault = function( value, defaultValue ) { + if ( defaultValue ) { + return `value=${ defaultValue }`; + } + return value; +}; + +const getType = function( param, defaultValue ) { + if ( ! defaultValue ) { + defaultValue = param.default; + } + + if ( param.type.type ) { + return getType( param.type, defaultValue ); + } else if ( param.expression ) { + if ( param.type === 'RestType' ) { + return `...${ getType( param.expression, defaultValue ) }`; + } else if ( param.type === 'NullableType' ) { + return `?${ getType( param.expression, defaultValue ) }`; + } else if ( param.type === 'TypeApplication' ) { + return `${ getType( param.expression, defaultValue ) }<${ + param.applications.map( ( application ) => getType( application ) ).join( ',' ) + }>`; + } else if ( param.type === 'OptionalType' ) { + return `[${ getType( param.expression, defaultValue ) }]`; + } + return getType( param.expression, defaultValue ); + } else if ( param.elements ) { + const types = param.elements.map( ( element ) => getType( element ) ); + return maybeAddDefault( `(${ types.join( '|' ) })`, defaultValue ); + } else if ( param.type === 'AllLiteral' ) { + return maybeAddDefault( '*', defaultValue ); + } else if ( param.type === 'NullLiteral' ) { + return maybeAddDefault( 'null', defaultValue ); + } else if ( param.type === 'UndefinedLiteral' ) { + return maybeAddDefault( 'undefined', defaultValue ); + } + + return maybeAddDefault( param.name, defaultValue ); +}; + +module.exports = function( param ) { + return getType( param ); +}; diff --git a/packages/docgen/src/index.js b/packages/docgen/src/index.js new file mode 100644 index 00000000000000..1bc2e71a37897a --- /dev/null +++ b/packages/docgen/src/index.js @@ -0,0 +1,126 @@ +/** + * External dependencies + */ +const fs = require( 'fs' ); +const path = require( 'path' ); +const { last } = require( 'lodash' ); + +/** + * Internal dependencies + */ +const engine = require( './engine' ); +const defaultMarkdownFormatter = require( './markdown' ); + +/** + * Helpers functions. + */ + +const relativeToAbsolute = ( basePath, relativePath ) => { + const target = path.join( path.dirname( basePath ), relativePath ); + if ( path.extname( target ) === '.js' ) { + return target; + } + let targetFile = target + '.js'; + if ( fs.existsSync( targetFile ) ) { + return targetFile; + } + targetFile = path.join( target, 'index.js' ); + if ( fs.existsSync( targetFile ) ) { + return targetFile; + } + process.stdout.write( '\nRelative path does not exists.' ); + process.stdout.write( '\n' ); + process.stdout.write( `\nBase: ${ basePath }` ); + process.stdout.write( `\nRelative: ${ relativePath }` ); + process.stdout.write( '\n\n' ); + process.exit( 1 ); +}; + +const getIRFromRelativePath = ( rootDir, basePath ) => ( relativePath ) => { + if ( ! relativePath.startsWith( '.' ) ) { + return []; + } + const absolutePath = relativeToAbsolute( basePath, relativePath ); + const result = processFile( rootDir, absolutePath ); + return result.ir || undefined; +}; + +const processFile = ( rootDir, inputFile ) => { + try { + const data = fs.readFileSync( inputFile, 'utf8' ); + currentFileStack.push( inputFile ); + const relativePath = path.relative( rootDir, inputFile ); + const result = engine( relativePath, data, getIRFromRelativePath( rootDir, last( currentFileStack ) ) ); + currentFileStack.pop( inputFile ); + return result; + } catch ( e ) { + process.stdout.write( `\n${ e }` ); + process.stdout.write( '\n\n' ); + process.exit( 1 ); + } +}; + +const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols, headingTitle ) => { + try { + const customFormatter = require( customFormatterFile ); + const output = customFormatter( rootDir, doc, symbols, headingTitle ); + fs.writeFileSync( doc, output ); + } catch ( e ) { + process.stdout.write( `\n${ e }` ); + process.stdout.write( '\n\n' ); + process.exit( 1 ); + } + return 'custom formatter'; +}; + +// To keep track of file being processed. +const currentFileStack = []; + +module.exports = function( sourceFile, options ) { + // Input: process CLI args, prepare files, etc + const processDir = process.cwd(); + if ( sourceFile === undefined ) { + process.stdout.write( '\n' ); + process.stdout.write( 'No source file provided' ); + process.stdout.write( '\n\n' ); + process.exit( 1 ); + } + sourceFile = path.join( processDir, sourceFile ); + + const debugMode = options.debug ? true : false; + + const inputBase = path.join( + path.dirname( sourceFile ), + path.basename( sourceFile, path.extname( sourceFile ) ) + ); + const ast = inputBase + '-ast.json'; + const tokens = inputBase + '-exports.json'; + const ir = inputBase + '-ir.json'; + const doc = options.output ? + path.join( processDir, options.output ) : + inputBase + '-api.md'; + + // Process + const result = processFile( processDir, sourceFile ); + const filteredIr = result.ir.filter( ( { name } ) => options.ignore ? ! name.match( options.ignore ) : true ); + + // Ouput + if ( result === undefined ) { + process.stdout.write( '\nFile was processed, but contained no ES6 module exports:' ); + process.stdout.write( `\n${ sourceFile }` ); + process.stdout.write( '\n\n' ); + process.exit( 0 ); + } + + if ( options.formatter ) { + runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr, 'API' ); + } else { + defaultMarkdownFormatter( options, processDir, doc, filteredIr, 'API' ); + } + + if ( debugMode ) { + fs.writeFileSync( ir, JSON.stringify( result.ir ) ); + fs.writeFileSync( tokens, JSON.stringify( result.tokens ) ); + fs.writeFileSync( ast, JSON.stringify( result.ast ) ); + } +}; diff --git a/packages/docgen/src/markdown/embed.js b/packages/docgen/src/markdown/embed.js new file mode 100644 index 00000000000000..9b52064c3377a4 --- /dev/null +++ b/packages/docgen/src/markdown/embed.js @@ -0,0 +1,51 @@ +/** + * External dependencies + */ +const { findLast } = require( 'lodash' ); + +const getHeadingIndex = ( ast, index ) => { + const astBeforeIndex = ast.children.slice( 0, index ); + const lastHeading = findLast( astBeforeIndex, ( node ) => node.type === 'heading' ); + return lastHeading ? lastHeading.depth : 1; +}; + +/** + * Inserts new contents within the token boundaries. + * + * @param {string} token String to embed in the start/end tokens. + * @param {Object} targetAst The remark AST of the file where the new contents are to be embedded. + * @param {Object} newContentAst The new contents to be embedded in remark AST format. + * @return {boolean} Whether the contents were embedded or not. + */ +const embed = function( token, targetAst, newContentAst ) { + let headingIndex = -1; + + const START_TOKEN = ``; + const END_TOKEN = ``; + const startIndex = targetAst.children.findIndex( + ( node ) => node.type === 'html' && node.value === START_TOKEN + ); + if ( startIndex === -1 ) { + return false; + } + const endIndex = targetAst.children.findIndex( + ( node ) => node.type === 'html' && node.value === END_TOKEN + ); + if ( endIndex === -1 ) { + return false; + } + + if ( startIndex !== -1 && endIndex !== -1 && startIndex < endIndex ) { + headingIndex = getHeadingIndex( targetAst, startIndex ); + newContentAst.children.forEach( ( node ) => { + if ( node.type === 'heading' ) { + node.depth = headingIndex + 1; + } + } ); + targetAst.children.splice( startIndex + 1, endIndex - startIndex - 1, newContentAst ); + return true; + } + return false; +}; + +module.exports = embed; diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js new file mode 100644 index 00000000000000..d9e41536f2f9a0 --- /dev/null +++ b/packages/docgen/src/markdown/formatter.js @@ -0,0 +1,128 @@ +/** + * External dependencies + */ +const path = require( 'path' ); + +const getTagsByName = ( tags, ...names ) => tags.filter( ( tag ) => names.some( ( name ) => name === tag.title ) ); + +const cleanSpaces = ( paragraph ) => + paragraph ? + paragraph.split( '\n' ).map( + ( sentence ) => sentence.trim() + ).reduce( + ( acc, current ) => acc + ' ' + current, + '' + ).trim() : + ''; + +const formatTag = ( title, tags, formatter, docs ) => { + if ( tags && tags.length > 0 ) { + docs.push( '\n' ); + docs.push( '\n' ); + docs.push( `**${ title }**` ); + docs.push( '\n' ); + docs.push( ...tags.map( formatter ) ); + } +}; + +const formatExamples = ( tags, docs ) => { + if ( tags && tags.length > 0 ) { + docs.push( '\n' ); + docs.push( '\n' ); + docs.push( '**Usage**' ); + docs.push( '\n' ); + docs.push( '\n' ); + docs.push( ...tags.map( + ( tag ) => `${ tag.description }` + ).join( '\n\n' ) ); + } +}; + +const formatDeprecated = ( tags, docs ) => { + if ( tags && tags.length > 0 ) { + docs.push( '\n' ); + docs.push( ...tags.map( + ( tag ) => `\n> **Deprecated** ${ cleanSpaces( tag.description ) }` + ) ); + } +}; + +const formatDescription = ( description, docs ) => { + docs.push( '\n' ); + docs.push( '\n' ); + docs.push( description ); +}; + +const getHeading = ( index, text ) => { + return '#'.repeat( index ) + ' ' + text; +}; + +module.exports = function( rootDir, docPath, symbols, headingTitle, headingStartIndex ) { + const docs = [ ]; + let headingIndex = headingStartIndex || 1; + if ( headingTitle ) { + docs.push( getHeading( headingIndex, `${ headingTitle }` ) ); + headingIndex++; + } + docs.push( '\n' ); + docs.push( '\n' ); + symbols.sort( ( first, second ) => { + const firstName = first.name.toUpperCase(); + const secondName = second.name.toUpperCase(); + if ( firstName < secondName ) { + return -1; + } + if ( firstName > secondName ) { + return 1; + } + return 0; + } ); + if ( symbols && symbols.length > 0 ) { + symbols.forEach( ( symbol ) => { + const symbolPath = path.join( + path.relative( + path.dirname( docPath ), + path.join( rootDir, path.dirname( symbol.path ) ) + ), + path.basename( symbol.path ), + ); + const symbolPathWithLines = `${ symbolPath }#L${ symbol.lineStart }-L${ symbol.lineEnd }`; + docs.push( getHeading( headingIndex, `${ symbol.name }` ) ); + docs.push( `\n\n[${ symbolPathWithLines }](${ symbolPathWithLines })` ); + formatDeprecated( getTagsByName( symbol.tags, 'deprecated' ), docs ); + formatDescription( symbol.description, docs ); + formatTag( + 'Related', + getTagsByName( symbol.tags, 'see', 'link' ), + ( tag ) => `\n- ${ tag.description }`, + docs + ); + formatExamples( getTagsByName( symbol.tags, 'example' ), docs ); + formatTag( + 'Type', + getTagsByName( symbol.tags, 'type' ), + ( tag ) => `\n\`${ tag.type }\` ${ cleanSpaces( tag.description ) }`, + docs + ); + formatTag( + 'Parameters', + getTagsByName( symbol.tags, 'param' ), + ( tag ) => `\n- **${ tag.name }** \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, + docs + ); + formatTag( + 'Returns', + getTagsByName( symbol.tags, 'return' ), + ( tag ) => `\n\`${ tag.type }\` ${ cleanSpaces( tag.description ) }`, + docs + ); + docs.push( '\n' ); + docs.push( '\n' ); + } ); + docs.pop(); // remove last \n, we want one blank line at the end of the file. + } else { + docs.push( 'Nothing to document.' ); + docs.push( '\n' ); + } + return docs.join( '' ); +}; diff --git a/packages/docgen/src/markdown/index.js b/packages/docgen/src/markdown/index.js new file mode 100644 index 00000000000000..499e211e1873a4 --- /dev/null +++ b/packages/docgen/src/markdown/index.js @@ -0,0 +1,44 @@ +/** + * External dependencies. + */ +const remark = require( 'remark' ); +const unified = require( 'unified' ); +const remarkParser = require( 'remark-parse' ); +const inject = require( 'mdast-util-inject' ); +const fs = require( 'fs' ); + +/** + * Internal dependencies. + */ +const formatter = require( './formatter' ); +const embed = require( './embed' ); + +const appendOrEmbedContents = ( { options, newContents } ) => { + return function transform( targetAst, file, next ) { + if ( options.toSection && ! inject( options.toSection, targetAst, newContents ) ) { + return next( new Error( `Heading ${ options.toSection } not found.` ) ); + } else if ( options.toToken && ! embed( options.useToken, targetAst, newContents ) ) { + return next( new Error( `Start and/or end tokens for ${ options.useToken } not found.` ) ); + } + next(); + }; +}; + +module.exports = function( options, processDir, doc, filteredIr, headingTitle ) { + if ( options.toSection || options.toToken ) { + const currentReadmeFile = fs.readFileSync( options.output, 'utf8' ); + const newContents = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIr, null ) ); + remark() + .use( { settings: { commonmark: true } } ) + .use( appendOrEmbedContents, { options, newContents } ) + .process( currentReadmeFile, function( err, file ) { + if ( err ) { + throw err; + } + fs.writeFileSync( doc, file ); + } ); + } else { + const output = formatter( processDir, doc, filteredIr, headingTitle ); + fs.writeFileSync( doc, output ); + } +}; diff --git a/packages/docgen/src/test/engine.js b/packages/docgen/src/test/engine.js new file mode 100644 index 00000000000000..3a9efc921a2f01 --- /dev/null +++ b/packages/docgen/src/test/engine.js @@ -0,0 +1,11 @@ +/** + * Internal dependencies. + */ +const engine = require( '../engine' ); + +describe( 'Engine', () => { + it( 'should return a void IR for undefined code', () => { + const { ir } = engine( undefined ); + expect( ir ).toHaveLength( 0 ); + } ); +} ); diff --git a/packages/docgen/src/test/fixtures/default-class-anonymous/code.js b/packages/docgen/src/test/fixtures/default-class-anonymous/code.js new file mode 100644 index 00000000000000..79ca0d6a39fcdb --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-class-anonymous/code.js @@ -0,0 +1,4 @@ +/** + * Class declaration example. + */ +export default class {} diff --git a/packages/docgen/src/test/fixtures/default-class-anonymous/exports.json b/packages/docgen/src/test/fixtures/default-class-anonymous/exports.json new file mode 100644 index 00000000000000..858f07abe98df9 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-class-anonymous/exports.json @@ -0,0 +1,82 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 38, + "end": 61, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 23 + } + }, + "range": [ + 38, + 61 + ], + "declaration": { + "type": "ClassDeclaration", + "start": 53, + "end": 61, + "loc": { + "start": { + "line": 4, + "column": 15 + }, + "end": { + "line": 4, + "column": 23 + } + }, + "range": [ + 53, + 61 + ], + "id": null, + "superClass": null, + "body": { + "type": "ClassBody", + "start": 59, + "end": 61, + "loc": { + "start": { + "line": 4, + "column": 21 + }, + "end": { + "line": 4, + "column": 23 + } + }, + "range": [ + 59, + 61 + ], + "body": [] + } + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 0, + "end": 37, + "range": [ + 0, + 37 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-class-named/code.js b/packages/docgen/src/test/fixtures/default-class-named/code.js new file mode 100644 index 00000000000000..91649c8da44b53 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-class-named/code.js @@ -0,0 +1,4 @@ +/** + * Class declaration example. + */ +export default class ClassDeclaration {} diff --git a/packages/docgen/src/test/fixtures/default-class-named/exports.json b/packages/docgen/src/test/fixtures/default-class-named/exports.json new file mode 100644 index 00000000000000..7533ef32e60de0 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-class-named/exports.json @@ -0,0 +1,101 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 38, + "end": 78, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 38, + 78 + ], + "declaration": { + "type": "ClassDeclaration", + "start": 53, + "end": 78, + "loc": { + "start": { + "line": 4, + "column": 15 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 53, + 78 + ], + "id": { + "type": "Identifier", + "start": 59, + "end": 75, + "loc": { + "start": { + "line": 4, + "column": 21 + }, + "end": { + "line": 4, + "column": 37 + } + }, + "range": [ + 59, + 75 + ], + "name": "ClassDeclaration" + }, + "superClass": null, + "body": { + "type": "ClassBody", + "start": 76, + "end": 78, + "loc": { + "start": { + "line": 4, + "column": 38 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 76, + 78 + ], + "body": [] + } + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 0, + "end": 37, + "range": [ + 0, + 37 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-function-anonymous/code.js b/packages/docgen/src/test/fixtures/default-function-anonymous/code.js new file mode 100644 index 00000000000000..5c8c7e23a946c8 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-function-anonymous/code.js @@ -0,0 +1,4 @@ +/** + * Function declaration example. + */ +export default function() {} diff --git a/packages/docgen/src/test/fixtures/default-function-anonymous/exports.json b/packages/docgen/src/test/fixtures/default-function-anonymous/exports.json new file mode 100644 index 00000000000000..9d10cd6c962f0f --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-function-anonymous/exports.json @@ -0,0 +1,85 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 41, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 28 + } + }, + "range": [ + 41, + 69 + ], + "declaration": { + "type": "FunctionDeclaration", + "start": 56, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 15 + }, + "end": { + "line": 4, + "column": 28 + } + }, + "range": [ + 56, + 69 + ], + "id": null, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 67, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 26 + }, + "end": { + "line": 4, + "column": 28 + } + }, + "range": [ + 67, + 69 + ], + "body": [] + } + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-function-named/ast.json b/packages/docgen/src/test/fixtures/default-function-named/ast.json new file mode 100644 index 00000000000000..a082f805974d26 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-function-named/ast.json @@ -0,0 +1,148 @@ +{ + "type": "Program", + "start": 0, + "end": 84, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 42 + } + }, + "range": [ + 41, + 83 + ], + "body": [ + { + "type": "ExportDefaultDeclaration", + "start": 41, + "end": 83, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 42 + } + }, + "range": [ + 41, + 83 + ], + "declaration": { + "type": "FunctionDeclaration", + "start": 56, + "end": 83, + "loc": { + "start": { + "line": 4, + "column": 15 + }, + "end": { + "line": 4, + "column": 42 + } + }, + "range": [ + 56, + 83 + ], + "id": { + "type": "Identifier", + "start": 65, + "end": 78, + "loc": { + "start": { + "line": 4, + "column": 24 + }, + "end": { + "line": 4, + "column": 37 + } + }, + "range": [ + 65, + 78 + ], + "name": "myDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 81, + "end": 83, + "loc": { + "start": { + "line": 4, + "column": 40 + }, + "end": { + "line": 4, + "column": 42 + } + }, + "range": [ + 81, + 83 + ], + "body": [] + } + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] + } + ], + "sourceType": "module", + "comments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-function-named/code.js b/packages/docgen/src/test/fixtures/default-function-named/code.js new file mode 100644 index 00000000000000..74318a75d6ab93 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-function-named/code.js @@ -0,0 +1,4 @@ +/** + * Function declaration example. + */ +export default function myDeclaration() {} diff --git a/packages/docgen/src/test/fixtures/default-function-named/exports.json b/packages/docgen/src/test/fixtures/default-function-named/exports.json new file mode 100644 index 00000000000000..7765cbef0da6d9 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-function-named/exports.json @@ -0,0 +1,104 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 41, + "end": 83, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 42 + } + }, + "range": [ + 41, + 83 + ], + "declaration": { + "type": "FunctionDeclaration", + "start": 56, + "end": 83, + "loc": { + "start": { + "line": 4, + "column": 15 + }, + "end": { + "line": 4, + "column": 42 + } + }, + "range": [ + 56, + 83 + ], + "id": { + "type": "Identifier", + "start": 65, + "end": 78, + "loc": { + "start": { + "line": 4, + "column": 24 + }, + "end": { + "line": 4, + "column": 37 + } + }, + "range": [ + 65, + 78 + ], + "name": "myDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 81, + "end": 83, + "loc": { + "start": { + "line": 4, + "column": 40 + }, + "end": { + "line": 4, + "column": 42 + } + }, + "range": [ + 81, + 83 + ], + "body": [] + } + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-function-named/ir.json b/packages/docgen/src/test/fixtures/default-function-named/ir.json new file mode 100644 index 00000000000000..526885397806c0 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-function-named/ir.json @@ -0,0 +1,7 @@ +[ + { + "name": "default", + "description": "Function declaration example.", + "tags": [] + } +] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-identifier/ast.json b/packages/docgen/src/test/fixtures/default-identifier/ast.json new file mode 100644 index 00000000000000..d83f628004f7de --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-identifier/ast.json @@ -0,0 +1,165 @@ +{ + "type": "Program", + "start": 0, + "end": 98, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 6, + "column": 32 + } + }, + "range": [ + 38, + 97 + ], + "body": [ + { + "type": "ClassDeclaration", + "start": 38, + "end": 63, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 25 + } + }, + "range": [ + 38, + 63 + ], + "id": { + "type": "Identifier", + "start": 44, + "end": 60, + "loc": { + "start": { + "line": 4, + "column": 6 + }, + "end": { + "line": 4, + "column": 22 + } + }, + "range": [ + 44, + 60 + ], + "name": "ClassDeclaration" + }, + "superClass": null, + "body": { + "type": "ClassBody", + "start": 61, + "end": 63, + "loc": { + "start": { + "line": 4, + "column": 23 + }, + "end": { + "line": 4, + "column": 25 + } + }, + "range": [ + 61, + 63 + ], + "body": [] + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 0, + "end": 37, + "range": [ + 0, + 37 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportDefaultDeclaration", + "start": 65, + "end": 97, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 32 + } + }, + "range": [ + 65, + 97 + ], + "declaration": { + "type": "Identifier", + "start": 80, + "end": 96, + "loc": { + "start": { + "line": 6, + "column": 15 + }, + "end": { + "line": 6, + "column": 31 + } + }, + "range": [ + 80, + 96 + ], + "name": "ClassDeclaration" + } + } + ], + "sourceType": "module", + "comments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 0, + "end": 37, + "range": [ + 0, + 37 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-identifier/code.js b/packages/docgen/src/test/fixtures/default-identifier/code.js new file mode 100644 index 00000000000000..2a172ecc0578fa --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-identifier/code.js @@ -0,0 +1,6 @@ +/** + * Class declaration example. + */ +class ClassDeclaration {} + +export default ClassDeclaration; diff --git a/packages/docgen/src/test/fixtures/default-identifier/exports.json b/packages/docgen/src/test/fixtures/default-identifier/exports.json new file mode 100644 index 00000000000000..c5cb42d5ad4caa --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-identifier/exports.json @@ -0,0 +1,39 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 65, + "end": 97, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 32 + } + }, + "range": [ + 65, + 97 + ], + "declaration": { + "type": "Identifier", + "start": 80, + "end": 96, + "loc": { + "start": { + "line": 6, + "column": 15 + }, + "end": { + "line": 6, + "column": 31 + } + }, + "range": [ + 80, + 96 + ], + "name": "ClassDeclaration" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-import-default/ast.json b/packages/docgen/src/test/fixtures/default-import-default/ast.json new file mode 100644 index 00000000000000..ee77f27a561e76 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-default/ast.json @@ -0,0 +1,143 @@ +{ + "type": "Program", + "start": 0, + "end": 92, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 29 + } + }, + "range": [ + 0, + 91 + ], + "body": [ + { + "type": "ImportDeclaration", + "start": 0, + "end": 60, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 60 + } + }, + "range": [ + 0, + 60 + ], + "specifiers": [ + { + "type": "ImportDefaultSpecifier", + "start": 7, + "end": 20, + "loc": { + "start": { + "line": 1, + "column": 7 + }, + "end": { + "line": 1, + "column": 20 + } + }, + "range": [ + 7, + 20 + ], + "local": { + "type": "Identifier", + "start": 7, + "end": 20, + "loc": { + "start": { + "line": 1, + "column": 7 + }, + "end": { + "line": 1, + "column": 20 + } + }, + "range": [ + 7, + 20 + ], + "name": "fnDeclaration" + } + } + ], + "source": { + "type": "Literal", + "start": 26, + "end": 59, + "loc": { + "start": { + "line": 1, + "column": 26 + }, + "end": { + "line": 1, + "column": 59 + } + }, + "range": [ + 26, + 59 + ], + "value": "./default-import-default-module", + "raw": "'./default-import-default-module'" + } + }, + { + "type": "ExportDefaultDeclaration", + "start": 62, + "end": 91, + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 29 + } + }, + "range": [ + 62, + 91 + ], + "declaration": { + "type": "Identifier", + "start": 77, + "end": 90, + "loc": { + "start": { + "line": 3, + "column": 15 + }, + "end": { + "line": 3, + "column": 28 + } + }, + "range": [ + 77, + 90 + ], + "name": "fnDeclaration" + } + } + ], + "sourceType": "module", + "comments": [] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-import-default/code.js b/packages/docgen/src/test/fixtures/default-import-default/code.js new file mode 100644 index 00000000000000..70619a579c57bf --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-default/code.js @@ -0,0 +1,6 @@ +/** + * Internal dependencies + */ +import fnDeclaration from './module-code'; + +export default fnDeclaration; diff --git a/packages/docgen/src/test/fixtures/default-import-default/exports.json b/packages/docgen/src/test/fixtures/default-import-default/exports.json new file mode 100644 index 00000000000000..fd453ed3011007 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-default/exports.json @@ -0,0 +1,39 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 62, + "end": 91, + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 29 + } + }, + "range": [ + 62, + 91 + ], + "declaration": { + "type": "Identifier", + "start": 77, + "end": 90, + "loc": { + "start": { + "line": 3, + "column": 15 + }, + "end": { + "line": 3, + "column": 28 + } + }, + "range": [ + 77, + 90 + ], + "name": "fnDeclaration" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-import-default/module-code.js b/packages/docgen/src/test/fixtures/default-import-default/module-code.js new file mode 100644 index 00000000000000..4da030a5b9d0a1 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-default/module-code.js @@ -0,0 +1,6 @@ +/** + * Function declaration. + */ +function functionDeclaration() {} + +export default functionDeclaration; diff --git a/packages/docgen/src/test/fixtures/default-import-default/module-ir.json b/packages/docgen/src/test/fixtures/default-import-default/module-ir.json new file mode 100644 index 00000000000000..9aaa9dc2213f5c --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-default/module-ir.json @@ -0,0 +1,7 @@ +[ + { + "name": "default", + "description": "Function declaration.", + "tags": [] + } +] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-import-named/ast.json b/packages/docgen/src/test/fixtures/default-import-named/ast.json new file mode 100644 index 00000000000000..73947334d5ac83 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-named/ast.json @@ -0,0 +1,163 @@ +{ + "type": "Program", + "start": 0, + "end": 117, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 29 + } + }, + "range": [ + 0, + 116 + ], + "body": [ + { + "type": "ImportDeclaration", + "start": 0, + "end": 85, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 85 + } + }, + "range": [ + 0, + 85 + ], + "specifiers": [ + { + "type": "ImportSpecifier", + "start": 9, + "end": 45, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 45 + } + }, + "range": [ + 9, + 45 + ], + "imported": { + "type": "Identifier", + "start": 9, + "end": 28, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 28 + } + }, + "range": [ + 9, + 28 + ], + "name": "functionDeclaration" + }, + "local": { + "type": "Identifier", + "start": 32, + "end": 45, + "loc": { + "start": { + "line": 1, + "column": 32 + }, + "end": { + "line": 1, + "column": 45 + } + }, + "range": [ + 32, + 45 + ], + "name": "fnDeclaration" + } + } + ], + "source": { + "type": "Literal", + "start": 53, + "end": 84, + "loc": { + "start": { + "line": 1, + "column": 53 + }, + "end": { + "line": 1, + "column": 84 + } + }, + "range": [ + 53, + 84 + ], + "value": "./default-import-named-module", + "raw": "'./default-import-named-module'" + } + }, + { + "type": "ExportDefaultDeclaration", + "start": 87, + "end": 116, + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 29 + } + }, + "range": [ + 87, + 116 + ], + "declaration": { + "type": "Identifier", + "start": 102, + "end": 115, + "loc": { + "start": { + "line": 3, + "column": 15 + }, + "end": { + "line": 3, + "column": 28 + } + }, + "range": [ + 102, + 115 + ], + "name": "fnDeclaration" + } + } + ], + "sourceType": "module", + "comments": [] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-import-named/code.js b/packages/docgen/src/test/fixtures/default-import-named/code.js new file mode 100644 index 00000000000000..b8e89023444b51 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-named/code.js @@ -0,0 +1,6 @@ +/** + * Internal dependencies + */ +import { functionDeclaration as fnDeclaration } from './module-code'; + +export default fnDeclaration; diff --git a/packages/docgen/src/test/fixtures/default-import-named/exports.json b/packages/docgen/src/test/fixtures/default-import-named/exports.json new file mode 100644 index 00000000000000..25d0f6024356f9 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-named/exports.json @@ -0,0 +1,39 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 87, + "end": 116, + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 29 + } + }, + "range": [ + 87, + 116 + ], + "declaration": { + "type": "Identifier", + "start": 102, + "end": 115, + "loc": { + "start": { + "line": 3, + "column": 15 + }, + "end": { + "line": 3, + "column": 28 + } + }, + "range": [ + 102, + 115 + ], + "name": "fnDeclaration" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-import-named/module-code.js b/packages/docgen/src/test/fixtures/default-import-named/module-code.js new file mode 100644 index 00000000000000..7ec5c68c3fbb3d --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-named/module-code.js @@ -0,0 +1,6 @@ +/** + * Function declaration. + */ +function functionDeclaration() {} + +export { functionDeclaration }; diff --git a/packages/docgen/src/test/fixtures/default-import-named/module-ir.json b/packages/docgen/src/test/fixtures/default-import-named/module-ir.json new file mode 100644 index 00000000000000..3c04255485cb97 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-import-named/module-ir.json @@ -0,0 +1 @@ +[{"name":"functionDeclaration","description":"Function declaration.","tags":[]}] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-named-export/ast.json b/packages/docgen/src/test/fixtures/default-named-export/ast.json new file mode 100644 index 00000000000000..31fde5d2e6883f --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-named-export/ast.json @@ -0,0 +1,189 @@ +{ + "type": "Program", + "start": 0, + "end": 119, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 6, + "column": 35 + } + }, + "range": [ + 41, + 118 + ], + "body": [ + { + "type": "ExportNamedDeclaration", + "start": 41, + "end": 81, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 41, + 81 + ], + "declaration": { + "type": "FunctionDeclaration", + "start": 48, + "end": 81, + "loc": { + "start": { + "line": 4, + "column": 7 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 48, + 81 + ], + "id": { + "type": "Identifier", + "start": 57, + "end": 76, + "loc": { + "start": { + "line": 4, + "column": 16 + }, + "end": { + "line": 4, + "column": 35 + } + }, + "range": [ + 57, + 76 + ], + "name": "functionDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 79, + "end": 81, + "loc": { + "start": { + "line": 4, + "column": 38 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 79, + 81 + ], + "body": [] + } + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportDefaultDeclaration", + "start": 83, + "end": 118, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 35 + } + }, + "range": [ + 83, + 118 + ], + "declaration": { + "type": "Identifier", + "start": 98, + "end": 117, + "loc": { + "start": { + "line": 6, + "column": 15 + }, + "end": { + "line": 6, + "column": 34 + } + }, + "range": [ + 98, + 117 + ], + "name": "functionDeclaration" + } + } + ], + "sourceType": "module", + "comments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-named-export/code.js b/packages/docgen/src/test/fixtures/default-named-export/code.js new file mode 100644 index 00000000000000..bd45a875a5eb69 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-named-export/code.js @@ -0,0 +1,6 @@ +/** + * Function declaration example. + */ +export function functionDeclaration() {} + +export default functionDeclaration; diff --git a/packages/docgen/src/test/fixtures/default-named-export/exports.json b/packages/docgen/src/test/fixtures/default-named-export/exports.json new file mode 100644 index 00000000000000..b432555e4d7a43 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-named-export/exports.json @@ -0,0 +1,147 @@ +[ + { + "type": "ExportNamedDeclaration", + "start": 41, + "end": 81, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 41, + 81 + ], + "declaration": { + "type": "FunctionDeclaration", + "start": 48, + "end": 81, + "loc": { + "start": { + "line": 4, + "column": 7 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 48, + 81 + ], + "id": { + "type": "Identifier", + "start": 57, + "end": 76, + "loc": { + "start": { + "line": 4, + "column": 16 + }, + "end": { + "line": 4, + "column": 35 + } + }, + "range": [ + 57, + 76 + ], + "name": "functionDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 79, + "end": 81, + "loc": { + "start": { + "line": 4, + "column": 38 + }, + "end": { + "line": 4, + "column": 40 + } + }, + "range": [ + 79, + 81 + ], + "body": [] + } + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportDefaultDeclaration", + "start": 83, + "end": 118, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 35 + } + }, + "range": [ + 83, + 118 + ], + "declaration": { + "type": "Identifier", + "start": 98, + "end": 117, + "loc": { + "start": { + "line": 6, + "column": 15 + }, + "end": { + "line": 6, + "column": 34 + } + }, + "range": [ + 98, + 117 + ], + "name": "functionDeclaration" + } + } +] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-undocumented-nocomments/code.js b/packages/docgen/src/test/fixtures/default-undocumented-nocomments/code.js new file mode 100644 index 00000000000000..e82c517463fd04 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-undocumented-nocomments/code.js @@ -0,0 +1,3 @@ +const myDeclaration = function() {}; + +export default myDeclaration; diff --git a/packages/docgen/src/test/fixtures/default-undocumented-nocomments/exports.json b/packages/docgen/src/test/fixtures/default-undocumented-nocomments/exports.json new file mode 100644 index 00000000000000..ac0eef84379339 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-undocumented-nocomments/exports.json @@ -0,0 +1,39 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 38, + "end": 67, + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 29 + } + }, + "range": [ + 38, + 67 + ], + "declaration": { + "type": "Identifier", + "start": 53, + "end": 66, + "loc": { + "start": { + "line": 3, + "column": 15 + }, + "end": { + "line": 3, + "column": 28 + } + }, + "range": [ + 53, + 66 + ], + "name": "myDeclaration" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-undocumented-oneliner/code.js b/packages/docgen/src/test/fixtures/default-undocumented-oneliner/code.js new file mode 100644 index 00000000000000..11e8966dd62d1c --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-undocumented-oneliner/code.js @@ -0,0 +1,2 @@ +// This comment should be ignored +export default function() { } diff --git a/packages/docgen/src/test/fixtures/default-undocumented-oneliner/exports.json b/packages/docgen/src/test/fixtures/default-undocumented-oneliner/exports.json new file mode 100644 index 00000000000000..45c6ab79f09133 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-undocumented-oneliner/exports.json @@ -0,0 +1,85 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 34, + "end": 63, + "loc": { + "start": { + "line": 2, + "column": 0 + }, + "end": { + "line": 2, + "column": 29 + } + }, + "range": [ + 34, + 63 + ], + "declaration": { + "type": "FunctionDeclaration", + "start": 49, + "end": 63, + "loc": { + "start": { + "line": 2, + "column": 15 + }, + "end": { + "line": 2, + "column": 29 + } + }, + "range": [ + 49, + 63 + ], + "id": null, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 60, + "end": 63, + "loc": { + "start": { + "line": 2, + "column": 26 + }, + "end": { + "line": 2, + "column": 29 + } + }, + "range": [ + 60, + 63 + ], + "body": [] + } + }, + "leadingComments": [ + { + "type": "Line", + "value": " This comment should be ignored", + "start": 0, + "end": 33, + "range": [ + 0, + 33 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 33 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/default-variable/code.js b/packages/docgen/src/test/fixtures/default-variable/code.js new file mode 100644 index 00000000000000..2e1a56238583f6 --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-variable/code.js @@ -0,0 +1,4 @@ +/** + * Variable declaration example. + */ +export default true; diff --git a/packages/docgen/src/test/fixtures/default-variable/exports.json b/packages/docgen/src/test/fixtures/default-variable/exports.json new file mode 100644 index 00000000000000..e6204ba061364b --- /dev/null +++ b/packages/docgen/src/test/fixtures/default-variable/exports.json @@ -0,0 +1,62 @@ +{ + "type": "ExportDefaultDeclaration", + "start": 41, + "end": 61, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 20 + } + }, + "range": [ + 41, + 61 + ], + "declaration": { + "type": "Literal", + "start": 56, + "end": 60, + "loc": { + "start": { + "line": 4, + "column": 15 + }, + "end": { + "line": 4, + "column": 19 + } + }, + "range": [ + 56, + 60 + ], + "value": true, + "raw": "true" + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/markdown/code.js b/packages/docgen/src/test/fixtures/markdown/code.js new file mode 100644 index 00000000000000..8d4261e0f63289 --- /dev/null +++ b/packages/docgen/src/test/fixtures/markdown/code.js @@ -0,0 +1,24 @@ +/** + * A function that adds two parameters. + * + * @deprecated Use native addition instead. + * @since v2 + * + * @see addition + * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators + * + * @param {number} firstParam The first param to add. + * @param {number} secondParam The second param to add. + * + * @example + * + * ```js + * const addResult = sum( 1, 3 ); + * console.log( addResult ); // will yield 4 + * ``` + * + * @return {number} The result of adding the two params. + */ +export const sum = ( firstParam, secondParam ) => { + return firstParam + secondParam; +}; diff --git a/packages/docgen/src/test/fixtures/markdown/docs.md b/packages/docgen/src/test/fixtures/markdown/docs.md new file mode 100644 index 00000000000000..12baa9046d0280 --- /dev/null +++ b/packages/docgen/src/test/fixtures/markdown/docs.md @@ -0,0 +1,41 @@ +# Package docs + +This is some package docs. + +## API Docs + + + +### sum + +[code.js#L22-L24](code.js#L22-L24) + +> **Deprecated** Use native addition instead. + +A function that adds two parameters. + +**Related** + +- addition +- + +**Usage** + +```js +const addResult = sum( 1, 3 ); +console.log( addResult ); // will yield 4 +``` + +**Parameters** + +- **firstParam** `number`: The first param to add. +- **secondParam** `number`: The second param to add. + +**Returns** + +`number` The result of adding the two params. + + + + +After token content. diff --git a/packages/docgen/src/test/fixtures/named-class/code.js b/packages/docgen/src/test/fixtures/named-class/code.js new file mode 100644 index 00000000000000..8310ea0c9f7f17 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-class/code.js @@ -0,0 +1,4 @@ +/** + * My declaration example. + */ +export class MyDeclaration {} diff --git a/packages/docgen/src/test/fixtures/named-class/exports.json b/packages/docgen/src/test/fixtures/named-class/exports.json new file mode 100644 index 00000000000000..e6da37a8974a0a --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-class/exports.json @@ -0,0 +1,103 @@ +{ + "type": "ExportNamedDeclaration", + "start": 35, + "end": 64, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 29 + } + }, + "range": [ + 35, + 64 + ], + "declaration": { + "type": "ClassDeclaration", + "start": 42, + "end": 64, + "loc": { + "start": { + "line": 4, + "column": 7 + }, + "end": { + "line": 4, + "column": 29 + } + }, + "range": [ + 42, + 64 + ], + "id": { + "type": "Identifier", + "start": 48, + "end": 61, + "loc": { + "start": { + "line": 4, + "column": 13 + }, + "end": { + "line": 4, + "column": 26 + } + }, + "range": [ + 48, + 61 + ], + "name": "MyDeclaration" + }, + "superClass": null, + "body": { + "type": "ClassBody", + "start": 62, + "end": 64, + "loc": { + "start": { + "line": 4, + "column": 27 + }, + "end": { + "line": 4, + "column": 29 + } + }, + "range": [ + 62, + 64 + ], + "body": [] + } + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-default-exported/code.js b/packages/docgen/src/test/fixtures/named-default-exported/code.js new file mode 100644 index 00000000000000..7aebc3a91fa1c3 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default-exported/code.js @@ -0,0 +1 @@ +export { default as moduleName } from './named-default-module'; diff --git a/packages/docgen/src/test/fixtures/named-default-exported/exports.json b/packages/docgen/src/test/fixtures/named-default-exported/exports.json new file mode 100644 index 00000000000000..5cfbfc16615810 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default-exported/exports.json @@ -0,0 +1,102 @@ +{ + "type": "ExportNamedDeclaration", + "start": 0, + "end": 63, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 63 + } + }, + "range": [ + 0, + 63 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 9, + "end": 30, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 30 + } + }, + "range": [ + 9, + 30 + ], + "local": { + "type": "Identifier", + "start": 9, + "end": 16, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 16 + } + }, + "range": [ + 9, + 16 + ], + "name": "default" + }, + "exported": { + "type": "Identifier", + "start": 20, + "end": 30, + "loc": { + "start": { + "line": 1, + "column": 20 + }, + "end": { + "line": 1, + "column": 30 + } + }, + "range": [ + 20, + 30 + ], + "name": "moduleName" + } + } + ], + "source": { + "type": "Literal", + "start": 38, + "end": 62, + "loc": { + "start": { + "line": 1, + "column": 38 + }, + "end": { + "line": 1, + "column": 62 + } + }, + "range": [ + 38, + 62 + ], + "value": "./named-default-module", + "raw": "'./named-default-module'" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-default-exported/module-code.js b/packages/docgen/src/test/fixtures/named-default-exported/module-code.js new file mode 100644 index 00000000000000..92127f1f850593 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default-exported/module-code.js @@ -0,0 +1,4 @@ +/** + * Module declaration. + */ +export default function( ) {} diff --git a/packages/docgen/src/test/fixtures/named-default-exported/module-ir.json b/packages/docgen/src/test/fixtures/named-default-exported/module-ir.json new file mode 100644 index 00000000000000..9e9b2ce30509ed --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default-exported/module-ir.json @@ -0,0 +1,5 @@ +[{ + "name": "default", + "description": "Module declaration.", + "tags": [] +}] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-default/code.js b/packages/docgen/src/test/fixtures/named-default/code.js new file mode 100644 index 00000000000000..441f6e366117f8 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default/code.js @@ -0,0 +1 @@ +export { default } from './module-code'; diff --git a/packages/docgen/src/test/fixtures/named-default/exports.json b/packages/docgen/src/test/fixtures/named-default/exports.json new file mode 100644 index 00000000000000..fd3a3c79d6a8b3 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default/exports.json @@ -0,0 +1,102 @@ +{ + "type": "ExportNamedDeclaration", + "start": 0, + "end": 49, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 49 + } + }, + "range": [ + 0, + 49 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 9, + "end": 16, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 16 + } + }, + "range": [ + 9, + 16 + ], + "local": { + "type": "Identifier", + "start": 9, + "end": 16, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 16 + } + }, + "range": [ + 9, + 16 + ], + "name": "default" + }, + "exported": { + "type": "Identifier", + "start": 9, + "end": 16, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 16 + } + }, + "range": [ + 9, + 16 + ], + "name": "default" + } + } + ], + "source": { + "type": "Literal", + "start": 24, + "end": 48, + "loc": { + "start": { + "line": 1, + "column": 24 + }, + "end": { + "line": 1, + "column": 48 + } + }, + "range": [ + 24, + 48 + ], + "value": "./named-default-module", + "raw": "'./named-default-module'" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-default/module-code.js b/packages/docgen/src/test/fixtures/named-default/module-code.js new file mode 100644 index 00000000000000..92127f1f850593 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default/module-code.js @@ -0,0 +1,4 @@ +/** + * Module declaration. + */ +export default function( ) {} diff --git a/packages/docgen/src/test/fixtures/named-default/module-ir.json b/packages/docgen/src/test/fixtures/named-default/module-ir.json new file mode 100644 index 00000000000000..9e9b2ce30509ed --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-default/module-ir.json @@ -0,0 +1,5 @@ +[{ + "name": "default", + "description": "Module declaration.", + "tags": [] +}] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-function/code.js b/packages/docgen/src/test/fixtures/named-function/code.js new file mode 100644 index 00000000000000..eadb279918d042 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-function/code.js @@ -0,0 +1,4 @@ +/** + * My declaration example. + */ +export function myDeclaration() {} diff --git a/packages/docgen/src/test/fixtures/named-function/exports.json b/packages/docgen/src/test/fixtures/named-function/exports.json new file mode 100644 index 00000000000000..8de0b612c6af6d --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-function/exports.json @@ -0,0 +1,106 @@ +{ + "type": "ExportNamedDeclaration", + "start": 35, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 34 + } + }, + "range": [ + 35, + 69 + ], + "declaration": { + "type": "FunctionDeclaration", + "start": 42, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 7 + }, + "end": { + "line": 4, + "column": 34 + } + }, + "range": [ + 42, + 69 + ], + "id": { + "type": "Identifier", + "start": 51, + "end": 64, + "loc": { + "start": { + "line": 4, + "column": 16 + }, + "end": { + "line": 4, + "column": 29 + } + }, + "range": [ + 51, + 64 + ], + "name": "myDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 67, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 32 + }, + "end": { + "line": 4, + "column": 34 + } + }, + "range": [ + 67, + 69 + ], + "body": [] + } + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-function/ir.json b/packages/docgen/src/test/fixtures/named-function/ir.json new file mode 100644 index 00000000000000..a9d9ab4175c9c5 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-function/ir.json @@ -0,0 +1,7 @@ +[ + { + "name": "myDeclaration", + "description": "My declaration example.", + "tags": [] + } +] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifier-destructuring/ast.json b/packages/docgen/src/test/fixtures/named-identifier-destructuring/ast.json new file mode 100644 index 00000000000000..9c17f5ad7401d9 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifier-destructuring/ast.json @@ -0,0 +1,381 @@ +{ + "type": "Program", + "start": 0, + "end": 141, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 6, + "column": 44 + } + }, + "range": [ + 35, + 140 + ], + "body": [ + { + "type": "VariableDeclaration", + "start": 35, + "end": 94, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 59 + } + }, + "range": [ + 35, + 94 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 41, + "end": 93, + "loc": { + "start": { + "line": 4, + "column": 6 + }, + "end": { + "line": 4, + "column": 58 + } + }, + "range": [ + 41, + 93 + ], + "id": { + "type": "ObjectPattern", + "start": 41, + "end": 60, + "loc": { + "start": { + "line": 4, + "column": 6 + }, + "end": { + "line": 4, + "column": 25 + } + }, + "range": [ + 41, + 60 + ], + "properties": [ + { + "type": "Property", + "start": 43, + "end": 58, + "loc": { + "start": { + "line": 4, + "column": 8 + }, + "end": { + "line": 4, + "column": 23 + } + }, + "range": [ + 43, + 58 + ], + "method": false, + "shorthand": true, + "computed": false, + "key": { + "type": "Identifier", + "start": 43, + "end": 58, + "loc": { + "start": { + "line": 4, + "column": 8 + }, + "end": { + "line": 4, + "column": 23 + } + }, + "range": [ + 43, + 58 + ], + "name": "someDeclaration" + }, + "kind": "init", + "value": { + "type": "Identifier", + "start": 43, + "end": 58, + "loc": { + "start": { + "line": 4, + "column": 8 + }, + "end": { + "line": 4, + "column": 23 + } + }, + "range": [ + 43, + 58 + ], + "name": "someDeclaration" + } + } + ] + }, + "init": { + "type": "ObjectExpression", + "start": 63, + "end": 93, + "loc": { + "start": { + "line": 4, + "column": 28 + }, + "end": { + "line": 4, + "column": 58 + } + }, + "range": [ + 63, + 93 + ], + "properties": [ + { + "type": "Property", + "start": 65, + "end": 91, + "loc": { + "start": { + "line": 4, + "column": 30 + }, + "end": { + "line": 4, + "column": 56 + } + }, + "range": [ + 65, + 91 + ], + "method": false, + "shorthand": false, + "computed": false, + "key": { + "type": "Identifier", + "start": 65, + "end": 80, + "loc": { + "start": { + "line": 4, + "column": 30 + }, + "end": { + "line": 4, + "column": 45 + } + }, + "range": [ + 65, + 80 + ], + "name": "someDeclaration" + }, + "value": { + "type": "ArrowFunctionExpression", + "start": 82, + "end": 91, + "loc": { + "start": { + "line": 4, + "column": 47 + }, + "end": { + "line": 4, + "column": 56 + } + }, + "range": [ + 82, + 91 + ], + "id": null, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 88, + "end": 91, + "loc": { + "start": { + "line": 4, + "column": 53 + }, + "end": { + "line": 4, + "column": 56 + } + }, + "range": [ + 88, + 91 + ], + "body": [] + } + }, + "kind": "init" + } + ] + } + } + ], + "kind": "const", + "leadingComments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportNamedDeclaration", + "start": 96, + "end": 140, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 44 + } + }, + "range": [ + 96, + 140 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 105, + "end": 137, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 41 + } + }, + "range": [ + 105, + 137 + ], + "local": { + "type": "Identifier", + "start": 105, + "end": 120, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 24 + } + }, + "range": [ + 105, + 120 + ], + "name": "someDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 124, + "end": 137, + "loc": { + "start": { + "line": 6, + "column": 28 + }, + "end": { + "line": 6, + "column": 41 + } + }, + "range": [ + 124, + 137 + ], + "name": "myDeclaration" + } + } + ], + "source": null + } + ], + "sourceType": "module", + "comments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifier-destructuring/code.js b/packages/docgen/src/test/fixtures/named-identifier-destructuring/code.js new file mode 100644 index 00000000000000..d5e1b5d46160d9 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifier-destructuring/code.js @@ -0,0 +1,6 @@ +/** + * My declaration example. + */ +const { someDeclaration } = { someDeclaration: () => { } }; + +export { someDeclaration as myDeclaration }; diff --git a/packages/docgen/src/test/fixtures/named-identifier-destructuring/exports.json b/packages/docgen/src/test/fixtures/named-identifier-destructuring/exports.json new file mode 100644 index 00000000000000..ac2695f1c68fa2 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifier-destructuring/exports.json @@ -0,0 +1,82 @@ +{ + "type": "ExportNamedDeclaration", + "start": 96, + "end": 140, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 44 + } + }, + "range": [ + 96, + 140 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 105, + "end": 137, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 41 + } + }, + "range": [ + 105, + 137 + ], + "local": { + "type": "Identifier", + "start": 105, + "end": 120, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 24 + } + }, + "range": [ + 105, + 120 + ], + "name": "someDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 124, + "end": 137, + "loc": { + "start": { + "line": 6, + "column": 28 + }, + "end": { + "line": 6, + "column": 41 + } + }, + "range": [ + 124, + 137 + ], + "name": "myDeclaration" + } + } + ], + "source": null +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifier/ast.json b/packages/docgen/src/test/fixtures/named-identifier/ast.json new file mode 100644 index 00000000000000..40eb2039185e3d --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifier/ast.json @@ -0,0 +1,211 @@ +{ + "type": "Program", + "start": 0, + "end": 90, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 6, + "column": 25 + } + }, + "range": [ + 35, + 89 + ], + "body": [ + { + "type": "FunctionDeclaration", + "start": 35, + "end": 62, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 27 + } + }, + "range": [ + 35, + 62 + ], + "id": { + "type": "Identifier", + "start": 44, + "end": 57, + "loc": { + "start": { + "line": 4, + "column": 9 + }, + "end": { + "line": 4, + "column": 22 + } + }, + "range": [ + 44, + 57 + ], + "name": "myDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 60, + "end": 62, + "loc": { + "start": { + "line": 4, + "column": 25 + }, + "end": { + "line": 4, + "column": 27 + } + }, + "range": [ + 60, + 62 + ], + "body": [] + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportNamedDeclaration", + "start": 64, + "end": 89, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 25 + } + }, + "range": [ + 64, + 89 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 73, + "end": 86, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 22 + } + }, + "range": [ + 73, + 86 + ], + "local": { + "type": "Identifier", + "start": 73, + "end": 86, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 22 + } + }, + "range": [ + 73, + 86 + ], + "name": "myDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 73, + "end": 86, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 22 + } + }, + "range": [ + 73, + 86 + ], + "name": "myDeclaration" + } + } + ], + "source": null + } + ], + "sourceType": "module", + "comments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifier/code.js b/packages/docgen/src/test/fixtures/named-identifier/code.js new file mode 100644 index 00000000000000..8fbd063086c192 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifier/code.js @@ -0,0 +1,6 @@ +/** + * My declaration example. + */ +function myDeclaration() {} + +export { myDeclaration }; diff --git a/packages/docgen/src/test/fixtures/named-identifier/exports.json b/packages/docgen/src/test/fixtures/named-identifier/exports.json new file mode 100644 index 00000000000000..3c2c7680042cfb --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifier/exports.json @@ -0,0 +1,82 @@ +{ + "type": "ExportNamedDeclaration", + "start": 64, + "end": 89, + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 6, + "column": 25 + } + }, + "range": [ + 64, + 89 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 73, + "end": 86, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 22 + } + }, + "range": [ + 73, + 86 + ], + "local": { + "type": "Identifier", + "start": 73, + "end": 86, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 22 + } + }, + "range": [ + 73, + 86 + ], + "name": "myDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 73, + "end": 86, + "loc": { + "start": { + "line": 6, + "column": 9 + }, + "end": { + "line": 6, + "column": 22 + } + }, + "range": [ + 73, + 86 + ], + "name": "myDeclaration" + } + } + ], + "source": null +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifiers-and-inline/ast.json b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/ast.json new file mode 100644 index 00000000000000..d761a6035d6c2b --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/ast.json @@ -0,0 +1,561 @@ +{ + "type": "Program", + "start": 0, + "end": 275, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 16, + "column": 40 + } + }, + "range": [ + 41, + 273 + ], + "body": [ + { + "type": "FunctionDeclaration", + "start": 41, + "end": 74, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 33 + } + }, + "range": [ + 41, + 74 + ], + "id": { + "type": "Identifier", + "start": 50, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 9 + }, + "end": { + "line": 4, + "column": 28 + } + }, + "range": [ + 50, + 69 + ], + "name": "functionDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 72, + "end": 74, + "loc": { + "start": { + "line": 4, + "column": 31 + }, + "end": { + "line": 4, + "column": 33 + } + }, + "range": [ + 72, + 74 + ], + "body": [] + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ], + "trailingComments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 76, + "end": 113, + "range": [ + 76, + 113 + ], + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 8, + "column": 3 + } + } + } + ] + }, + { + "type": "ClassDeclaration", + "start": 114, + "end": 139, + "loc": { + "start": { + "line": 9, + "column": 0 + }, + "end": { + "line": 9, + "column": 25 + } + }, + "range": [ + 114, + 139 + ], + "id": { + "type": "Identifier", + "start": 120, + "end": 136, + "loc": { + "start": { + "line": 9, + "column": 6 + }, + "end": { + "line": 9, + "column": 22 + } + }, + "range": [ + 120, + 136 + ], + "name": "ClassDeclaration" + }, + "superClass": null, + "body": { + "type": "ClassBody", + "start": 137, + "end": 139, + "loc": { + "start": { + "line": 9, + "column": 23 + }, + "end": { + "line": 9, + "column": 25 + } + }, + "range": [ + 137, + 139 + ], + "body": [] + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 76, + "end": 113, + "range": [ + 76, + 113 + ], + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 8, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportNamedDeclaration", + "start": 141, + "end": 190, + "loc": { + "start": { + "line": 11, + "column": 0 + }, + "end": { + "line": 11, + "column": 49 + } + }, + "range": [ + 141, + 190 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 150, + "end": 169, + "loc": { + "start": { + "line": 11, + "column": 9 + }, + "end": { + "line": 11, + "column": 28 + } + }, + "range": [ + 150, + 169 + ], + "local": { + "type": "Identifier", + "start": 150, + "end": 169, + "loc": { + "start": { + "line": 11, + "column": 9 + }, + "end": { + "line": 11, + "column": 28 + } + }, + "range": [ + 150, + 169 + ], + "name": "functionDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 150, + "end": 169, + "loc": { + "start": { + "line": 11, + "column": 9 + }, + "end": { + "line": 11, + "column": 28 + } + }, + "range": [ + 150, + 169 + ], + "name": "functionDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 171, + "end": 187, + "loc": { + "start": { + "line": 11, + "column": 30 + }, + "end": { + "line": 11, + "column": 46 + } + }, + "range": [ + 171, + 187 + ], + "local": { + "type": "Identifier", + "start": 171, + "end": 187, + "loc": { + "start": { + "line": 11, + "column": 30 + }, + "end": { + "line": 11, + "column": 46 + } + }, + "range": [ + 171, + 187 + ], + "name": "ClassDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 171, + "end": 187, + "loc": { + "start": { + "line": 11, + "column": 30 + }, + "end": { + "line": 11, + "column": 46 + } + }, + "range": [ + 171, + 187 + ], + "name": "ClassDeclaration" + } + } + ], + "source": null, + "trailingComments": [ + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 192, + "end": 232, + "range": [ + 192, + 232 + ], + "loc": { + "start": { + "line": 13, + "column": 0 + }, + "end": { + "line": 15, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportNamedDeclaration", + "start": 233, + "end": 273, + "loc": { + "start": { + "line": 16, + "column": 0 + }, + "end": { + "line": 16, + "column": 40 + } + }, + "range": [ + 233, + 273 + ], + "declaration": { + "type": "VariableDeclaration", + "start": 240, + "end": 273, + "loc": { + "start": { + "line": 16, + "column": 7 + }, + "end": { + "line": 16, + "column": 40 + } + }, + "range": [ + 240, + 273 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 246, + "end": 272, + "loc": { + "start": { + "line": 16, + "column": 13 + }, + "end": { + "line": 16, + "column": 39 + } + }, + "range": [ + 246, + 272 + ], + "id": { + "type": "Identifier", + "start": 246, + "end": 265, + "loc": { + "start": { + "line": 16, + "column": 13 + }, + "end": { + "line": 16, + "column": 32 + } + }, + "range": [ + 246, + 265 + ], + "name": "variableDeclaration" + }, + "init": { + "type": "Literal", + "start": 268, + "end": 272, + "loc": { + "start": { + "line": 16, + "column": 35 + }, + "end": { + "line": 16, + "column": 39 + } + }, + "range": [ + 268, + 272 + ], + "value": true, + "raw": "true" + } + } + ], + "kind": "const" + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 192, + "end": 232, + "range": [ + 192, + 232 + ], + "loc": { + "start": { + "line": 13, + "column": 0 + }, + "end": { + "line": 15, + "column": 3 + } + } + } + ] + } + ], + "sourceType": "module", + "comments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + }, + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 76, + "end": 113, + "range": [ + 76, + 113 + ], + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 8, + "column": 3 + } + } + }, + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 192, + "end": 232, + "range": [ + 192, + 232 + ], + "loc": { + "start": { + "line": 13, + "column": 0 + }, + "end": { + "line": 15, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifiers-and-inline/code.js b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/code.js new file mode 100644 index 00000000000000..10b836d597856f --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/code.js @@ -0,0 +1,17 @@ +/** + * Function declaration example. + */ +function functionDeclaration() {} + +/** + * Class declaration example. + */ +class ClassDeclaration {} + +export { functionDeclaration, ClassDeclaration }; + +/** + * Variable declaration example. + */ +export const variableDeclaration = true; + diff --git a/packages/docgen/src/test/fixtures/named-identifiers-and-inline/exports.json b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/exports.json new file mode 100644 index 00000000000000..960e07f08fd7c8 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/exports.json @@ -0,0 +1,290 @@ +[ + { + "type": "ExportNamedDeclaration", + "start": 141, + "end": 190, + "loc": { + "start": { + "line": 11, + "column": 0 + }, + "end": { + "line": 11, + "column": 49 + } + }, + "range": [ + 141, + 190 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 150, + "end": 169, + "loc": { + "start": { + "line": 11, + "column": 9 + }, + "end": { + "line": 11, + "column": 28 + } + }, + "range": [ + 150, + 169 + ], + "local": { + "type": "Identifier", + "start": 150, + "end": 169, + "loc": { + "start": { + "line": 11, + "column": 9 + }, + "end": { + "line": 11, + "column": 28 + } + }, + "range": [ + 150, + 169 + ], + "name": "functionDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 150, + "end": 169, + "loc": { + "start": { + "line": 11, + "column": 9 + }, + "end": { + "line": 11, + "column": 28 + } + }, + "range": [ + 150, + 169 + ], + "name": "functionDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 171, + "end": 187, + "loc": { + "start": { + "line": 11, + "column": 30 + }, + "end": { + "line": 11, + "column": 46 + } + }, + "range": [ + 171, + 187 + ], + "local": { + "type": "Identifier", + "start": 171, + "end": 187, + "loc": { + "start": { + "line": 11, + "column": 30 + }, + "end": { + "line": 11, + "column": 46 + } + }, + "range": [ + 171, + 187 + ], + "name": "ClassDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 171, + "end": 187, + "loc": { + "start": { + "line": 11, + "column": 30 + }, + "end": { + "line": 11, + "column": 46 + } + }, + "range": [ + 171, + 187 + ], + "name": "ClassDeclaration" + } + } + ], + "source": null, + "trailingComments": [ + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 192, + "end": 232, + "range": [ + 192, + 232 + ], + "loc": { + "start": { + "line": 13, + "column": 0 + }, + "end": { + "line": 15, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportNamedDeclaration", + "start": 233, + "end": 273, + "loc": { + "start": { + "line": 16, + "column": 0 + }, + "end": { + "line": 16, + "column": 40 + } + }, + "range": [ + 233, + 273 + ], + "declaration": { + "type": "VariableDeclaration", + "start": 240, + "end": 273, + "loc": { + "start": { + "line": 16, + "column": 7 + }, + "end": { + "line": 16, + "column": 40 + } + }, + "range": [ + 240, + 273 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 246, + "end": 272, + "loc": { + "start": { + "line": 16, + "column": 13 + }, + "end": { + "line": 16, + "column": 39 + } + }, + "range": [ + 246, + 272 + ], + "id": { + "type": "Identifier", + "start": 246, + "end": 265, + "loc": { + "start": { + "line": 16, + "column": 13 + }, + "end": { + "line": 16, + "column": 32 + } + }, + "range": [ + 246, + 265 + ], + "name": "variableDeclaration" + }, + "init": { + "type": "Literal", + "start": 268, + "end": 272, + "loc": { + "start": { + "line": 16, + "column": 35 + }, + "end": { + "line": 16, + "column": 39 + } + }, + "range": [ + 268, + 272 + ], + "value": true, + "raw": "true" + } + } + ], + "kind": "const" + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 192, + "end": 232, + "range": [ + 192, + 232 + ], + "loc": { + "start": { + "line": 13, + "column": 0 + }, + "end": { + "line": 15, + "column": 3 + } + } + } + ] + } +] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifiers/ast.json b/packages/docgen/src/test/fixtures/named-identifiers/ast.json new file mode 100644 index 00000000000000..f6aa5b92541abc --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifiers/ast.json @@ -0,0 +1,599 @@ +{ + "type": "Program", + "start": 0, + "end": 288, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 16, + "column": 70 + } + }, + "range": [ + 41, + 287 + ], + "body": [ + { + "type": "FunctionDeclaration", + "start": 41, + "end": 74, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 33 + } + }, + "range": [ + 41, + 74 + ], + "id": { + "type": "Identifier", + "start": 50, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 9 + }, + "end": { + "line": 4, + "column": 28 + } + }, + "range": [ + 50, + 69 + ], + "name": "functionDeclaration" + }, + "generator": false, + "expression": false, + "async": false, + "params": [], + "body": { + "type": "BlockStatement", + "start": 72, + "end": 74, + "loc": { + "start": { + "line": 4, + "column": 31 + }, + "end": { + "line": 4, + "column": 33 + } + }, + "range": [ + 72, + 74 + ], + "body": [] + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ], + "trailingComments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 76, + "end": 113, + "range": [ + 76, + 113 + ], + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 8, + "column": 3 + } + } + } + ] + }, + { + "type": "ClassDeclaration", + "start": 114, + "end": 139, + "loc": { + "start": { + "line": 9, + "column": 0 + }, + "end": { + "line": 9, + "column": 25 + } + }, + "range": [ + 114, + 139 + ], + "id": { + "type": "Identifier", + "start": 120, + "end": 136, + "loc": { + "start": { + "line": 9, + "column": 6 + }, + "end": { + "line": 9, + "column": 22 + } + }, + "range": [ + 120, + 136 + ], + "name": "ClassDeclaration" + }, + "superClass": null, + "body": { + "type": "ClassBody", + "start": 137, + "end": 139, + "loc": { + "start": { + "line": 9, + "column": 23 + }, + "end": { + "line": 9, + "column": 25 + } + }, + "range": [ + 137, + 139 + ], + "body": [] + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 76, + "end": 113, + "range": [ + 76, + 113 + ], + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 8, + "column": 3 + } + } + } + ], + "trailingComments": [ + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 141, + "end": 181, + "range": [ + 141, + 181 + ], + "loc": { + "start": { + "line": 11, + "column": 0 + }, + "end": { + "line": 13, + "column": 3 + } + } + } + ] + }, + { + "type": "VariableDeclaration", + "start": 182, + "end": 215, + "loc": { + "start": { + "line": 14, + "column": 0 + }, + "end": { + "line": 14, + "column": 33 + } + }, + "range": [ + 182, + 215 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 188, + "end": 214, + "loc": { + "start": { + "line": 14, + "column": 6 + }, + "end": { + "line": 14, + "column": 32 + } + }, + "range": [ + 188, + 214 + ], + "id": { + "type": "Identifier", + "start": 188, + "end": 207, + "loc": { + "start": { + "line": 14, + "column": 6 + }, + "end": { + "line": 14, + "column": 25 + } + }, + "range": [ + 188, + 207 + ], + "name": "variableDeclaration" + }, + "init": { + "type": "Literal", + "start": 210, + "end": 214, + "loc": { + "start": { + "line": 14, + "column": 28 + }, + "end": { + "line": 14, + "column": 32 + } + }, + "range": [ + 210, + 214 + ], + "value": true, + "raw": "true" + } + } + ], + "kind": "const", + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 141, + "end": 181, + "range": [ + 141, + 181 + ], + "loc": { + "start": { + "line": 11, + "column": 0 + }, + "end": { + "line": 13, + "column": 3 + } + } + } + ] + }, + { + "type": "ExportNamedDeclaration", + "start": 217, + "end": 287, + "loc": { + "start": { + "line": 16, + "column": 0 + }, + "end": { + "line": 16, + "column": 70 + } + }, + "range": [ + 217, + 287 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 226, + "end": 245, + "loc": { + "start": { + "line": 16, + "column": 9 + }, + "end": { + "line": 16, + "column": 28 + } + }, + "range": [ + 226, + 245 + ], + "local": { + "type": "Identifier", + "start": 226, + "end": 245, + "loc": { + "start": { + "line": 16, + "column": 9 + }, + "end": { + "line": 16, + "column": 28 + } + }, + "range": [ + 226, + 245 + ], + "name": "functionDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 226, + "end": 245, + "loc": { + "start": { + "line": 16, + "column": 9 + }, + "end": { + "line": 16, + "column": 28 + } + }, + "range": [ + 226, + 245 + ], + "name": "functionDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 247, + "end": 266, + "loc": { + "start": { + "line": 16, + "column": 30 + }, + "end": { + "line": 16, + "column": 49 + } + }, + "range": [ + 247, + 266 + ], + "local": { + "type": "Identifier", + "start": 247, + "end": 266, + "loc": { + "start": { + "line": 16, + "column": 30 + }, + "end": { + "line": 16, + "column": 49 + } + }, + "range": [ + 247, + 266 + ], + "name": "variableDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 247, + "end": 266, + "loc": { + "start": { + "line": 16, + "column": 30 + }, + "end": { + "line": 16, + "column": 49 + } + }, + "range": [ + 247, + 266 + ], + "name": "variableDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 268, + "end": 284, + "loc": { + "start": { + "line": 16, + "column": 51 + }, + "end": { + "line": 16, + "column": 67 + } + }, + "range": [ + 268, + 284 + ], + "local": { + "type": "Identifier", + "start": 268, + "end": 284, + "loc": { + "start": { + "line": 16, + "column": 51 + }, + "end": { + "line": 16, + "column": 67 + } + }, + "range": [ + 268, + 284 + ], + "name": "ClassDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 268, + "end": 284, + "loc": { + "start": { + "line": 16, + "column": 51 + }, + "end": { + "line": 16, + "column": 67 + } + }, + "range": [ + 268, + 284 + ], + "name": "ClassDeclaration" + } + } + ], + "source": null + } + ], + "sourceType": "module", + "comments": [ + { + "type": "Block", + "value": "*\n * Function declaration example.\n ", + "start": 0, + "end": 40, + "range": [ + 0, + 40 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + }, + { + "type": "Block", + "value": "*\n * Class declaration example.\n ", + "start": 76, + "end": 113, + "range": [ + 76, + 113 + ], + "loc": { + "start": { + "line": 6, + "column": 0 + }, + "end": { + "line": 8, + "column": 3 + } + } + }, + { + "type": "Block", + "value": "*\n * Variable declaration example.\n ", + "start": 141, + "end": 181, + "range": [ + 141, + 181 + ], + "loc": { + "start": { + "line": 11, + "column": 0 + }, + "end": { + "line": 13, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifiers/code.js b/packages/docgen/src/test/fixtures/named-identifiers/code.js new file mode 100644 index 00000000000000..6c608a4eea4e7a --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifiers/code.js @@ -0,0 +1,16 @@ +/** + * Function declaration example. + */ +function functionDeclaration() {} + +/** + * Class declaration example. + */ +class ClassDeclaration {} + +/** + * Variable declaration example. + */ +const variableDeclaration = true; + +export { functionDeclaration, variableDeclaration, ClassDeclaration }; diff --git a/packages/docgen/src/test/fixtures/named-identifiers/exports.json b/packages/docgen/src/test/fixtures/named-identifiers/exports.json new file mode 100644 index 00000000000000..eb1e017e311b42 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifiers/exports.json @@ -0,0 +1,200 @@ +{ + "type": "ExportNamedDeclaration", + "start": 217, + "end": 287, + "loc": { + "start": { + "line": 16, + "column": 0 + }, + "end": { + "line": 16, + "column": 70 + } + }, + "range": [ + 217, + 287 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 226, + "end": 245, + "loc": { + "start": { + "line": 16, + "column": 9 + }, + "end": { + "line": 16, + "column": 28 + } + }, + "range": [ + 226, + 245 + ], + "local": { + "type": "Identifier", + "start": 226, + "end": 245, + "loc": { + "start": { + "line": 16, + "column": 9 + }, + "end": { + "line": 16, + "column": 28 + } + }, + "range": [ + 226, + 245 + ], + "name": "functionDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 226, + "end": 245, + "loc": { + "start": { + "line": 16, + "column": 9 + }, + "end": { + "line": 16, + "column": 28 + } + }, + "range": [ + 226, + 245 + ], + "name": "functionDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 247, + "end": 266, + "loc": { + "start": { + "line": 16, + "column": 30 + }, + "end": { + "line": 16, + "column": 49 + } + }, + "range": [ + 247, + 266 + ], + "local": { + "type": "Identifier", + "start": 247, + "end": 266, + "loc": { + "start": { + "line": 16, + "column": 30 + }, + "end": { + "line": 16, + "column": 49 + } + }, + "range": [ + 247, + 266 + ], + "name": "variableDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 247, + "end": 266, + "loc": { + "start": { + "line": 16, + "column": 30 + }, + "end": { + "line": 16, + "column": 49 + } + }, + "range": [ + 247, + 266 + ], + "name": "variableDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 268, + "end": 284, + "loc": { + "start": { + "line": 16, + "column": 51 + }, + "end": { + "line": 16, + "column": 67 + } + }, + "range": [ + 268, + 284 + ], + "local": { + "type": "Identifier", + "start": 268, + "end": 284, + "loc": { + "start": { + "line": 16, + "column": 51 + }, + "end": { + "line": 16, + "column": 67 + } + }, + "range": [ + 268, + 284 + ], + "name": "ClassDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 268, + "end": 284, + "loc": { + "start": { + "line": 16, + "column": 51 + }, + "end": { + "line": 16, + "column": 67 + } + }, + "range": [ + 268, + 284 + ], + "name": "ClassDeclaration" + } + } + ], + "source": null +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-identifiers/ir.json b/packages/docgen/src/test/fixtures/named-identifiers/ir.json new file mode 100644 index 00000000000000..ab7e9787fa15f4 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-identifiers/ir.json @@ -0,0 +1 @@ +[{"name":"ClassDeclaration","description":"Class declaration example.","tags":[]},{"name":"functionDeclaration","description":"Function declaration example.","tags":[]},{"name":"variableDeclaration","description":"Variable declaration example.","tags":[]}] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-import-named/code.js b/packages/docgen/src/test/fixtures/named-import-named/code.js new file mode 100644 index 00000000000000..68e9b4499792c7 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-named/code.js @@ -0,0 +1,5 @@ +export { + functionDeclaration, + variableDeclaration, + ClassDeclaration, +} from './named-identifiers'; diff --git a/packages/docgen/src/test/fixtures/named-import-named/exports.json b/packages/docgen/src/test/fixtures/named-import-named/exports.json new file mode 100644 index 00000000000000..8d3340586992f9 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-named/exports.json @@ -0,0 +1,220 @@ +{ + "type": "ExportNamedDeclaration", + "start": 0, + "end": 101, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 5, + "column": 29 + } + }, + "range": [ + 0, + 101 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 10, + "end": 29, + "loc": { + "start": { + "line": 2, + "column": 1 + }, + "end": { + "line": 2, + "column": 20 + } + }, + "range": [ + 10, + 29 + ], + "local": { + "type": "Identifier", + "start": 10, + "end": 29, + "loc": { + "start": { + "line": 2, + "column": 1 + }, + "end": { + "line": 2, + "column": 20 + } + }, + "range": [ + 10, + 29 + ], + "name": "functionDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 10, + "end": 29, + "loc": { + "start": { + "line": 2, + "column": 1 + }, + "end": { + "line": 2, + "column": 20 + } + }, + "range": [ + 10, + 29 + ], + "name": "functionDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 32, + "end": 51, + "loc": { + "start": { + "line": 3, + "column": 1 + }, + "end": { + "line": 3, + "column": 20 + } + }, + "range": [ + 32, + 51 + ], + "local": { + "type": "Identifier", + "start": 32, + "end": 51, + "loc": { + "start": { + "line": 3, + "column": 1 + }, + "end": { + "line": 3, + "column": 20 + } + }, + "range": [ + 32, + 51 + ], + "name": "variableDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 32, + "end": 51, + "loc": { + "start": { + "line": 3, + "column": 1 + }, + "end": { + "line": 3, + "column": 20 + } + }, + "range": [ + 32, + 51 + ], + "name": "variableDeclaration" + } + }, + { + "type": "ExportSpecifier", + "start": 54, + "end": 70, + "loc": { + "start": { + "line": 4, + "column": 1 + }, + "end": { + "line": 4, + "column": 17 + } + }, + "range": [ + 54, + 70 + ], + "local": { + "type": "Identifier", + "start": 54, + "end": 70, + "loc": { + "start": { + "line": 4, + "column": 1 + }, + "end": { + "line": 4, + "column": 17 + } + }, + "range": [ + 54, + 70 + ], + "name": "ClassDeclaration" + }, + "exported": { + "type": "Identifier", + "start": 54, + "end": 70, + "loc": { + "start": { + "line": 4, + "column": 1 + }, + "end": { + "line": 4, + "column": 17 + } + }, + "range": [ + 54, + 70 + ], + "name": "ClassDeclaration" + } + } + ], + "source": { + "type": "Literal", + "start": 79, + "end": 100, + "loc": { + "start": { + "line": 5, + "column": 7 + }, + "end": { + "line": 5, + "column": 28 + } + }, + "range": [ + 79, + 100 + ], + "value": "./named-identifiers", + "raw": "'./named-identifiers'" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-import-namespace/ast.json b/packages/docgen/src/test/fixtures/named-import-namespace/ast.json new file mode 100644 index 00000000000000..f17b43fcef7533 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-namespace/ast.json @@ -0,0 +1,186 @@ +{ + "type": "Program", + "start": 0, + "end": 85, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 21 + } + }, + "range": [ + 0, + 84 + ], + "body": [ + { + "type": "ImportDeclaration", + "start": 0, + "end": 61, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 61 + } + }, + "range": [ + 0, + 61 + ], + "specifiers": [ + { + "type": "ImportNamespaceSpecifier", + "start": 7, + "end": 21, + "loc": { + "start": { + "line": 1, + "column": 7 + }, + "end": { + "line": 1, + "column": 21 + } + }, + "range": [ + 7, + 21 + ], + "local": { + "type": "Identifier", + "start": 12, + "end": 21, + "loc": { + "start": { + "line": 1, + "column": 12 + }, + "end": { + "line": 1, + "column": 21 + } + }, + "range": [ + 12, + 21 + ], + "name": "variables" + } + } + ], + "source": { + "type": "Literal", + "start": 27, + "end": 60, + "loc": { + "start": { + "line": 1, + "column": 27 + }, + "end": { + "line": 1, + "column": 60 + } + }, + "range": [ + 27, + 60 + ], + "value": "./named-import-namespace-module", + "raw": "'./named-import-namespace-module'" + } + }, + { + "type": "ExportNamedDeclaration", + "start": 63, + "end": 84, + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 21 + } + }, + "range": [ + 63, + 84 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 72, + "end": 81, + "loc": { + "start": { + "line": 3, + "column": 9 + }, + "end": { + "line": 3, + "column": 18 + } + }, + "range": [ + 72, + 81 + ], + "local": { + "type": "Identifier", + "start": 72, + "end": 81, + "loc": { + "start": { + "line": 3, + "column": 9 + }, + "end": { + "line": 3, + "column": 18 + } + }, + "range": [ + 72, + 81 + ], + "name": "variables" + }, + "exported": { + "type": "Identifier", + "start": 72, + "end": 81, + "loc": { + "start": { + "line": 3, + "column": 9 + }, + "end": { + "line": 3, + "column": 18 + } + }, + "range": [ + 72, + 81 + ], + "name": "variables" + } + } + ], + "source": null + } + ], + "sourceType": "module", + "comments": [] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-import-namespace/code.js b/packages/docgen/src/test/fixtures/named-import-namespace/code.js new file mode 100644 index 00000000000000..a6b9234374d421 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-namespace/code.js @@ -0,0 +1,6 @@ +/** + * Internal dependencies + */ +import * as variables from './named-import-namespace-module'; + +export { variables }; diff --git a/packages/docgen/src/test/fixtures/named-import-namespace/exports.json b/packages/docgen/src/test/fixtures/named-import-namespace/exports.json new file mode 100644 index 00000000000000..a2ea24189479d3 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-namespace/exports.json @@ -0,0 +1,82 @@ +{ + "type": "ExportNamedDeclaration", + "start": 63, + "end": 84, + "loc": { + "start": { + "line": 3, + "column": 0 + }, + "end": { + "line": 3, + "column": 21 + } + }, + "range": [ + 63, + 84 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 72, + "end": 81, + "loc": { + "start": { + "line": 3, + "column": 9 + }, + "end": { + "line": 3, + "column": 18 + } + }, + "range": [ + 72, + 81 + ], + "local": { + "type": "Identifier", + "start": 72, + "end": 81, + "loc": { + "start": { + "line": 3, + "column": 9 + }, + "end": { + "line": 3, + "column": 18 + } + }, + "range": [ + 72, + 81 + ], + "name": "variables" + }, + "exported": { + "type": "Identifier", + "start": 72, + "end": 81, + "loc": { + "start": { + "line": 3, + "column": 9 + }, + "end": { + "line": 3, + "column": 18 + } + }, + "range": [ + 72, + 81 + ], + "name": "variables" + } + } + ], + "source": null +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-import-namespace/module-code.js b/packages/docgen/src/test/fixtures/named-import-namespace/module-code.js new file mode 100644 index 00000000000000..5c29fce8528403 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-namespace/module-code.js @@ -0,0 +1 @@ +export { default as controls } from './default-function-named'; diff --git a/packages/docgen/src/test/fixtures/named-import-namespace/module-exports.json b/packages/docgen/src/test/fixtures/named-import-namespace/module-exports.json new file mode 100644 index 00000000000000..3e467a9404209a --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-namespace/module-exports.json @@ -0,0 +1,102 @@ +{ + "type": "ExportNamedDeclaration", + "start": 0, + "end": 63, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 63 + } + }, + "range": [ + 0, + 63 + ], + "declaration": null, + "specifiers": [ + { + "type": "ExportSpecifier", + "start": 9, + "end": 28, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 28 + } + }, + "range": [ + 9, + 28 + ], + "local": { + "type": "Identifier", + "start": 9, + "end": 16, + "loc": { + "start": { + "line": 1, + "column": 9 + }, + "end": { + "line": 1, + "column": 16 + } + }, + "range": [ + 9, + 16 + ], + "name": "default" + }, + "exported": { + "type": "Identifier", + "start": 20, + "end": 28, + "loc": { + "start": { + "line": 1, + "column": 20 + }, + "end": { + "line": 1, + "column": 28 + } + }, + "range": [ + 20, + 28 + ], + "name": "controls" + } + } + ], + "source": { + "type": "Literal", + "start": 36, + "end": 62, + "loc": { + "start": { + "line": 1, + "column": 36 + }, + "end": { + "line": 1, + "column": 62 + } + }, + "range": [ + 36, + 62 + ], + "value": "./default-function-named", + "raw": "'./default-function-named'" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-import-namespace/module-ir.json b/packages/docgen/src/test/fixtures/named-import-namespace/module-ir.json new file mode 100644 index 00000000000000..6488f6035d0179 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-import-namespace/module-ir.json @@ -0,0 +1 @@ +[{"name":"controls","description":"Function declaration example.","tags":[]}] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-variable/code.js b/packages/docgen/src/test/fixtures/named-variable/code.js new file mode 100644 index 00000000000000..e89c8a9751394c --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-variable/code.js @@ -0,0 +1,5 @@ +/** + * My declaration example. + */ +export const myDeclaration = true; + diff --git a/packages/docgen/src/test/fixtures/named-variable/exports.json b/packages/docgen/src/test/fixtures/named-variable/exports.json new file mode 100644 index 00000000000000..1c5797990ceab8 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-variable/exports.json @@ -0,0 +1,125 @@ +{ + "type": "ExportNamedDeclaration", + "start": 35, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 34 + } + }, + "range": [ + 35, + 69 + ], + "declaration": { + "type": "VariableDeclaration", + "start": 42, + "end": 69, + "loc": { + "start": { + "line": 4, + "column": 7 + }, + "end": { + "line": 4, + "column": 34 + } + }, + "range": [ + 42, + 69 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 48, + "end": 68, + "loc": { + "start": { + "line": 4, + "column": 13 + }, + "end": { + "line": 4, + "column": 33 + } + }, + "range": [ + 48, + 68 + ], + "id": { + "type": "Identifier", + "start": 48, + "end": 61, + "loc": { + "start": { + "line": 4, + "column": 13 + }, + "end": { + "line": 4, + "column": 26 + } + }, + "range": [ + 48, + 61 + ], + "name": "myDeclaration" + }, + "init": { + "type": "Literal", + "start": 64, + "end": 68, + "loc": { + "start": { + "line": 4, + "column": 29 + }, + "end": { + "line": 4, + "column": 33 + } + }, + "range": [ + 64, + 68 + ], + "value": true, + "raw": "true" + } + } + ], + "kind": "const" + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/named-variables/code.js b/packages/docgen/src/test/fixtures/named-variables/code.js new file mode 100644 index 00000000000000..8f56e0aff46e5a --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-variables/code.js @@ -0,0 +1,6 @@ +/** + * My declaration example. + */ +export const firstDeclaration = true, + secondDeclaration = 42; + diff --git a/packages/docgen/src/test/fixtures/named-variables/exports.json b/packages/docgen/src/test/fixtures/named-variables/exports.json new file mode 100644 index 00000000000000..24d1d1525e9501 --- /dev/null +++ b/packages/docgen/src/test/fixtures/named-variables/exports.json @@ -0,0 +1,185 @@ +{ + "type": "ExportNamedDeclaration", + "start": 35, + "end": 97, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 5, + "column": 24 + } + }, + "range": [ + 35, + 97 + ], + "declaration": { + "type": "VariableDeclaration", + "start": 42, + "end": 97, + "loc": { + "start": { + "line": 4, + "column": 7 + }, + "end": { + "line": 5, + "column": 24 + } + }, + "range": [ + 42, + 97 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 48, + "end": 71, + "loc": { + "start": { + "line": 4, + "column": 13 + }, + "end": { + "line": 4, + "column": 36 + } + }, + "range": [ + 48, + 71 + ], + "id": { + "type": "Identifier", + "start": 48, + "end": 64, + "loc": { + "start": { + "line": 4, + "column": 13 + }, + "end": { + "line": 4, + "column": 29 + } + }, + "range": [ + 48, + 64 + ], + "name": "firstDeclaration" + }, + "init": { + "type": "Literal", + "start": 67, + "end": 71, + "loc": { + "start": { + "line": 4, + "column": 32 + }, + "end": { + "line": 4, + "column": 36 + } + }, + "range": [ + 67, + 71 + ], + "value": true, + "raw": "true" + } + }, + { + "type": "VariableDeclarator", + "start": 74, + "end": 96, + "loc": { + "start": { + "line": 5, + "column": 1 + }, + "end": { + "line": 5, + "column": 23 + } + }, + "range": [ + 74, + 96 + ], + "id": { + "type": "Identifier", + "start": 74, + "end": 91, + "loc": { + "start": { + "line": 5, + "column": 1 + }, + "end": { + "line": 5, + "column": 18 + } + }, + "range": [ + 74, + 91 + ], + "name": "secondDeclaration" + }, + "init": { + "type": "Literal", + "start": 94, + "end": 96, + "loc": { + "start": { + "line": 5, + "column": 21 + }, + "end": { + "line": 5, + "column": 23 + } + }, + "range": [ + 94, + 96 + ], + "value": 42, + "raw": "42" + } + } + ], + "kind": "const" + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * My declaration example.\n ", + "start": 0, + "end": 34, + "range": [ + 0, + 34 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/namespace-commented/code.js b/packages/docgen/src/test/fixtures/namespace-commented/code.js new file mode 100644 index 00000000000000..5008b26d090aa5 --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace-commented/code.js @@ -0,0 +1,4 @@ +/** + * This comment should be ignored. + */ +export * from './namespace-module'; diff --git a/packages/docgen/src/test/fixtures/namespace-commented/exports.json b/packages/docgen/src/test/fixtures/namespace-commented/exports.json new file mode 100644 index 00000000000000..37166ddd12a5ca --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace-commented/exports.json @@ -0,0 +1,62 @@ +{ + "type": "ExportAllDeclaration", + "start": 43, + "end": 78, + "loc": { + "start": { + "line": 4, + "column": 0 + }, + "end": { + "line": 4, + "column": 35 + } + }, + "range": [ + 43, + 78 + ], + "source": { + "type": "Literal", + "start": 57, + "end": 77, + "loc": { + "start": { + "line": 4, + "column": 14 + }, + "end": { + "line": 4, + "column": 34 + } + }, + "range": [ + 57, + 77 + ], + "value": "./namespace-module", + "raw": "'./namespace-module'" + }, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * This comment should be ignored.\n ", + "start": 0, + "end": 42, + "range": [ + 0, + 42 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 3, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/namespace-commented/module-ir.json b/packages/docgen/src/test/fixtures/namespace-commented/module-ir.json new file mode 100644 index 00000000000000..7798095b482fac --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace-commented/module-ir.json @@ -0,0 +1,22 @@ +[ + { + "name": "default", + "description": "Default variable declaration.", + "tags": [] + }, + { + "name": "MyClass", + "description": "Named class.", + "tags": [] + }, + { + "name": "myFunction", + "description": "Named function.", + "tags": [] + }, + { + "name": "myVariable", + "description": "Named variable.", + "tags": [] + } +] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/namespace-commented/module.js b/packages/docgen/src/test/fixtures/namespace-commented/module.js new file mode 100644 index 00000000000000..1ff51c686236af --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace-commented/module.js @@ -0,0 +1,19 @@ +/** + * Named variable. + */ +export const myVariable = true; + +/** + * Named function. + */ +export const myFunction = () => {}; + +/** + * Named class. + */ +export class MyClass {} + +/** + * Default variable declaration. + */ +export default 42; diff --git a/packages/docgen/src/test/fixtures/namespace/code.js b/packages/docgen/src/test/fixtures/namespace/code.js new file mode 100644 index 00000000000000..d2705ea5f8e632 --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace/code.js @@ -0,0 +1 @@ +export * from './namespace-module'; diff --git a/packages/docgen/src/test/fixtures/namespace/exports.json b/packages/docgen/src/test/fixtures/namespace/exports.json new file mode 100644 index 00000000000000..d6aa32af9ac61e --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace/exports.json @@ -0,0 +1,40 @@ +{ + "type": "ExportAllDeclaration", + "start": 0, + "end": 35, + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 1, + "column": 35 + } + }, + "range": [ + 0, + 35 + ], + "source": { + "type": "Literal", + "start": 14, + "end": 34, + "loc": { + "start": { + "line": 1, + "column": 14 + }, + "end": { + "line": 1, + "column": 34 + } + }, + "range": [ + 14, + 34 + ], + "value": "./namespace-module", + "raw": "'./namespace-module'" + } +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/namespace/module-ir.json b/packages/docgen/src/test/fixtures/namespace/module-ir.json new file mode 100644 index 00000000000000..7798095b482fac --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace/module-ir.json @@ -0,0 +1,22 @@ +[ + { + "name": "default", + "description": "Default variable declaration.", + "tags": [] + }, + { + "name": "MyClass", + "description": "Named class.", + "tags": [] + }, + { + "name": "myFunction", + "description": "Named function.", + "tags": [] + }, + { + "name": "myVariable", + "description": "Named variable.", + "tags": [] + } +] \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/namespace/module.js b/packages/docgen/src/test/fixtures/namespace/module.js new file mode 100644 index 00000000000000..1ff51c686236af --- /dev/null +++ b/packages/docgen/src/test/fixtures/namespace/module.js @@ -0,0 +1,19 @@ +/** + * Named variable. + */ +export const myVariable = true; + +/** + * Named function. + */ +export const myFunction = () => {}; + +/** + * Named class. + */ +export class MyClass {} + +/** + * Default variable declaration. + */ +export default 42; diff --git a/packages/docgen/src/test/fixtures/tags-function/code.js b/packages/docgen/src/test/fixtures/tags-function/code.js new file mode 100644 index 00000000000000..8d4261e0f63289 --- /dev/null +++ b/packages/docgen/src/test/fixtures/tags-function/code.js @@ -0,0 +1,24 @@ +/** + * A function that adds two parameters. + * + * @deprecated Use native addition instead. + * @since v2 + * + * @see addition + * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators + * + * @param {number} firstParam The first param to add. + * @param {number} secondParam The second param to add. + * + * @example + * + * ```js + * const addResult = sum( 1, 3 ); + * console.log( addResult ); // will yield 4 + * ``` + * + * @return {number} The result of adding the two params. + */ +export const sum = ( firstParam, secondParam ) => { + return firstParam + secondParam; +}; diff --git a/packages/docgen/src/test/fixtures/tags-function/exports.json b/packages/docgen/src/test/fixtures/tags-function/exports.json new file mode 100644 index 00000000000000..3d0677a818c4b6 --- /dev/null +++ b/packages/docgen/src/test/fixtures/tags-function/exports.json @@ -0,0 +1,269 @@ +{ + "type": "ExportNamedDeclaration", + "start": 521, + "end": 609, + "loc": { + "start": { + "line": 22, + "column": 0 + }, + "end": { + "line": 24, + "column": 2 + } + }, + "range": [ + 521, + 609 + ], + "declaration": { + "type": "VariableDeclaration", + "start": 528, + "end": 609, + "loc": { + "start": { + "line": 22, + "column": 7 + }, + "end": { + "line": 24, + "column": 2 + } + }, + "range": [ + 528, + 609 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 534, + "end": 608, + "loc": { + "start": { + "line": 22, + "column": 13 + }, + "end": { + "line": 24, + "column": 1 + } + }, + "range": [ + 534, + 608 + ], + "id": { + "type": "Identifier", + "start": 534, + "end": 537, + "loc": { + "start": { + "line": 22, + "column": 13 + }, + "end": { + "line": 22, + "column": 16 + } + }, + "range": [ + 534, + 537 + ], + "name": "sum" + }, + "init": { + "type": "ArrowFunctionExpression", + "start": 540, + "end": 608, + "loc": { + "start": { + "line": 22, + "column": 19 + }, + "end": { + "line": 24, + "column": 1 + } + }, + "range": [ + 540, + 608 + ], + "id": null, + "generator": false, + "expression": false, + "async": false, + "params": [ + { + "type": "Identifier", + "start": 542, + "end": 552, + "loc": { + "start": { + "line": 22, + "column": 21 + }, + "end": { + "line": 22, + "column": 31 + } + }, + "range": [ + 542, + 552 + ], + "name": "firstParam" + }, + { + "type": "Identifier", + "start": 554, + "end": 565, + "loc": { + "start": { + "line": 22, + "column": 33 + }, + "end": { + "line": 22, + "column": 44 + } + }, + "range": [ + 554, + 565 + ], + "name": "secondParam" + } + ], + "body": { + "type": "BlockStatement", + "start": 571, + "end": 608, + "loc": { + "start": { + "line": 22, + "column": 50 + }, + "end": { + "line": 24, + "column": 1 + } + }, + "range": [ + 571, + 608 + ], + "body": [ + { + "type": "ReturnStatement", + "start": 574, + "end": 606, + "loc": { + "start": { + "line": 23, + "column": 1 + }, + "end": { + "line": 23, + "column": 33 + } + }, + "range": [ + 574, + 606 + ], + "argument": { + "type": "BinaryExpression", + "start": 581, + "end": 605, + "loc": { + "start": { + "line": 23, + "column": 8 + }, + "end": { + "line": 23, + "column": 32 + } + }, + "range": [ + 581, + 605 + ], + "left": { + "type": "Identifier", + "start": 581, + "end": 591, + "loc": { + "start": { + "line": 23, + "column": 8 + }, + "end": { + "line": 23, + "column": 18 + } + }, + "range": [ + 581, + 591 + ], + "name": "firstParam" + }, + "operator": "+", + "right": { + "type": "Identifier", + "start": 594, + "end": 605, + "loc": { + "start": { + "line": 23, + "column": 21 + }, + "end": { + "line": 23, + "column": 32 + } + }, + "range": [ + 594, + 605 + ], + "name": "secondParam" + } + } + } + ] + } + } + } + ], + "kind": "const" + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n * @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ", + "start": 0, + "end": 520, + "range": [ + 0, + 520 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 21, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/fixtures/tags-variable/code.js b/packages/docgen/src/test/fixtures/tags-variable/code.js new file mode 100644 index 00000000000000..d2d32717a67bcb --- /dev/null +++ b/packages/docgen/src/test/fixtures/tags-variable/code.js @@ -0,0 +1,7 @@ +/** + * Constant to document the meaning of life, + * the universe and everything else. + * + * @type {number} + */ +export const THE_MEANING = 42; diff --git a/packages/docgen/src/test/fixtures/tags-variable/exports.json b/packages/docgen/src/test/fixtures/tags-variable/exports.json new file mode 100644 index 00000000000000..80482610d28e54 --- /dev/null +++ b/packages/docgen/src/test/fixtures/tags-variable/exports.json @@ -0,0 +1,125 @@ +{ + "type": "ExportNamedDeclaration", + "start": 111, + "end": 141, + "loc": { + "start": { + "line": 7, + "column": 0 + }, + "end": { + "line": 7, + "column": 30 + } + }, + "range": [ + 111, + 141 + ], + "declaration": { + "type": "VariableDeclaration", + "start": 118, + "end": 141, + "loc": { + "start": { + "line": 7, + "column": 7 + }, + "end": { + "line": 7, + "column": 30 + } + }, + "range": [ + 118, + 141 + ], + "declarations": [ + { + "type": "VariableDeclarator", + "start": 124, + "end": 140, + "loc": { + "start": { + "line": 7, + "column": 13 + }, + "end": { + "line": 7, + "column": 29 + } + }, + "range": [ + 124, + 140 + ], + "id": { + "type": "Identifier", + "start": 124, + "end": 135, + "loc": { + "start": { + "line": 7, + "column": 13 + }, + "end": { + "line": 7, + "column": 24 + } + }, + "range": [ + 124, + 135 + ], + "name": "THE_MEANING" + }, + "init": { + "type": "Literal", + "start": 138, + "end": 140, + "loc": { + "start": { + "line": 7, + "column": 27 + }, + "end": { + "line": 7, + "column": 29 + } + }, + "range": [ + 138, + 140 + ], + "value": 42, + "raw": "42" + } + } + ], + "kind": "const" + }, + "specifiers": [], + "source": null, + "leadingComments": [ + { + "type": "Block", + "value": "*\n * Constant to document the meaning of life,\n * the universe and everything else.\n *\n * @type {number}\n ", + "start": 0, + "end": 110, + "range": [ + 0, + 110 + ], + "loc": { + "start": { + "line": 1, + "column": 0 + }, + "end": { + "line": 6, + "column": 3 + } + } + } + ] +} \ No newline at end of file diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js new file mode 100644 index 00000000000000..cd7e66a12e2678 --- /dev/null +++ b/packages/docgen/src/test/formatter-markdown.js @@ -0,0 +1,34 @@ +/** + * Internal dependencies. + */ +const formatter = require( '../markdown/formatter' ); + +describe( 'Formatter', () => { + it( 'returns markdown', () => { + const rootDir = '/home/my-path'; + const docPath = '/home/my-path/docs'; + const docs = formatter( rootDir, docPath + '-api.md', [ { + path: docPath + '-code.js', + description: 'My declaration example.', + tags: [ + { + title: 'param', + description: 'First declaration parameter.', + type: 'number', + name: 'firstParam', + }, + { + title: 'return', + description: 'The result of the declaration.', + type: 'number', + }, + ], + name: 'myDeclaration', + lineStart: 1, + lineEnd: 2, + } ], 'API docs' ); + expect( docs ).toBe( + '# API docs\n\n## myDeclaration\n\n[home/my-path/docs-code.js#L1-L2](home/my-path/docs-code.js#L1-L2)\n\nMy declaration example.\n\n**Parameters**\n\n- **firstParam** `number`: First declaration parameter.\n\n**Returns**\n\n`number` The result of the declaration.\n' + ); + } ); +} ); diff --git a/packages/docgen/src/test/get-export-entries.js b/packages/docgen/src/test/get-export-entries.js new file mode 100644 index 00000000000000..b1e06f9d145a9c --- /dev/null +++ b/packages/docgen/src/test/get-export-entries.js @@ -0,0 +1,352 @@ +/** + * Node dependencies. + */ +const fs = require( 'fs' ); +const path = require( 'path' ); + +/** + * Internal dependencies. + */ +const getExportEntries = require( '../get-export-entries' ); + +describe( 'Export entries', function() { + it( 'default class (anonymous)', () => { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-class-anonymous/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: '*default*', + exportName: 'default', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'default class (named)', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-class-named/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'ClassDeclaration', + exportName: 'default', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'default function (anonymous)', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-function-anonymous/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: '*default*', + exportName: 'default', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'default function (named)', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-function-named/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'myDeclaration', + exportName: 'default', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'default identifier', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-identifier/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'ClassDeclaration', + exportName: 'default', + module: null, + lineStart: 6, + lineEnd: 6, + } ); + } ); + + it( 'default import (named)', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-import-named/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'fnDeclaration', + exportName: 'default', + module: null, + lineStart: 3, + lineEnd: 3, + } ); + } ); + + it( 'default import (default)', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-import-default/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'fnDeclaration', + exportName: 'default', + module: null, + lineStart: 3, + lineEnd: 3, + } ); + } ); + + it( 'default named export', function() { + const tokens = fs.readFileSync( + path.join( __dirname, './fixtures/default-named-export/exports.json' ), + 'utf-8' + ); + const namedExport = getExportEntries( JSON.parse( tokens )[ 0 ] ); + expect( namedExport ).toHaveLength( 1 ); + expect( namedExport[ 0 ] ).toEqual( { + localName: 'functionDeclaration', + exportName: 'functionDeclaration', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + const defaultExport = getExportEntries( JSON.parse( tokens )[ 1 ] ); + expect( defaultExport ).toHaveLength( 1 ); + expect( defaultExport[ 0 ] ).toEqual( { + localName: 'functionDeclaration', + exportName: 'default', + module: null, + lineStart: 6, + lineEnd: 6, + } ); + } ); + + it( 'default variable', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-variable/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: '*default*', + exportName: 'default', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'named class', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-class/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'MyDeclaration', + exportName: 'MyDeclaration', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'named default', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-default/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'default', + exportName: 'default', + module: './named-default-module', + lineStart: 1, + lineEnd: 1, + } ); + } ); + + it( 'named default (exported)', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-default-exported/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'default', + exportName: 'moduleName', + module: './named-default-module', + lineStart: 1, + lineEnd: 1, + } ); + } ); + + it( 'named function', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-function/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'myDeclaration', + exportName: 'myDeclaration', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'named identifier', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifier/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'myDeclaration', + exportName: 'myDeclaration', + module: null, + lineStart: 6, + lineEnd: 6, + } ); + const tokenObject = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifier-destructuring/exports.json' ), + 'utf-8' + ); + const nameObject = getExportEntries( JSON.parse( tokenObject ) ); + expect( nameObject ).toHaveLength( 1 ); + expect( nameObject[ 0 ] ).toEqual( { + localName: 'someDeclaration', + exportName: 'myDeclaration', + module: null, + lineStart: 6, + lineEnd: 6, + } ); + } ); + + it( 'named identifiers', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifiers/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 3 ); + expect( name[ 0 ] ).toEqual( + { localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 16, lineEnd: 16 } + ); + expect( name[ 1 ] ).toEqual( + { localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 }, + ); + expect( name[ 2 ] ).toEqual( + { localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 16, lineEnd: 16 }, + ); + const tokenIdentifiersAndInline = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifiers-and-inline/exports.json' ), + 'utf-8' + ); + const nameInline0 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 0 ] ); + expect( nameInline0 ).toHaveLength( 2 ); + expect( nameInline0[ 0 ] ).toEqual( + { localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 11, lineEnd: 11 }, + ); + expect( nameInline0[ 1 ] ).toEqual( + { localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 11, lineEnd: 11 }, + ); + const nameInline1 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 1 ] ); + expect( nameInline1 ).toHaveLength( 1 ); + expect( nameInline1[ 0 ] ).toEqual( + { localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 }, + ); + } ); + + it( 'named import namespace', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-import-namespace/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( + { localName: 'variables', exportName: 'variables', module: null, lineStart: 3, lineEnd: 3 }, + ); + } ); + + it( 'named variable', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-variable/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: 'myDeclaration', + exportName: 'myDeclaration', + module: null, + lineStart: 4, + lineEnd: 4, + } ); + } ); + + it( 'named variables', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-variables/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 2 ); + expect( name[ 0 ] ).toEqual( + { localName: 'firstDeclaration', exportName: 'firstDeclaration', module: null, lineStart: 4, lineEnd: 5 }, + ); + expect( name[ 1 ] ).toEqual( + { localName: 'secondDeclaration', exportName: 'secondDeclaration', module: null, lineStart: 4, lineEnd: 5 }, + ); + } ); + + it( 'namespace (*)', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/namespace/exports.json' ), + 'utf-8' + ); + const name = getExportEntries( JSON.parse( token ) ); + expect( name ).toHaveLength( 1 ); + expect( name[ 0 ] ).toEqual( { + localName: '*', + exportName: null, + module: './namespace-module', + lineStart: 1, + lineEnd: 1, + } ); + } ); +} ); diff --git a/packages/docgen/src/test/get-intermediate-representation.js b/packages/docgen/src/test/get-intermediate-representation.js new file mode 100644 index 00000000000000..53cb937a2be518 --- /dev/null +++ b/packages/docgen/src/test/get-intermediate-representation.js @@ -0,0 +1,454 @@ +/** + * Node dependencies. + */ +const fs = require( 'fs' ); +const path = require( 'path' ); + +/** + * Internal dependencies. + */ +const getIntermediateRepresentation = require( '../get-intermediate-representation' ); + +describe( 'Intermediate Representation', function() { + it( 'undocumented', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-undocumented-nocomments/exports.json' ), + 'utf-8' + ); + const ir = getIntermediateRepresentation( null, JSON.parse( token ) ); + expect( ir ).toHaveLength( 1 ); + expect( ir[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Undocumented declaration.', + tags: [], + lineStart: 3, + lineEnd: 3, + } ); + const tokenOneliner = fs.readFileSync( + path.join( __dirname, './fixtures/default-undocumented-oneliner/exports.json' ), + 'utf-8' + ); + const irOneliner = getIntermediateRepresentation( null, JSON.parse( tokenOneliner ) ); + expect( irOneliner ).toHaveLength( 1 ); + expect( irOneliner[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Undocumented declaration.', + tags: [], + lineStart: 2, + lineEnd: 2, + } ); + } ); + + describe( 'JSDoc in export statement', function() { + it( 'default export', function() { + const tokenClassAnonymous = fs.readFileSync( + path.join( __dirname, './fixtures/default-class-anonymous/exports.json' ), + 'utf-8' + ); + const irClassAnonymous = getIntermediateRepresentation( null, JSON.parse( tokenClassAnonymous ) ); + expect( irClassAnonymous ).toHaveLength( 1 ); + expect( irClassAnonymous[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Class declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + const tokenClassNamed = fs.readFileSync( + path.join( __dirname, './fixtures/default-class-named/exports.json' ), + 'utf-8' + ); + const irClassNamed = getIntermediateRepresentation( null, JSON.parse( tokenClassNamed ) ); + expect( irClassNamed ).toHaveLength( 1 ); + expect( irClassNamed[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Class declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + const tokenFnAnonymous = fs.readFileSync( + path.join( __dirname, './fixtures/default-function-anonymous/exports.json' ), + 'utf-8' + ); + const irFnAnonymous = getIntermediateRepresentation( null, JSON.parse( tokenFnAnonymous ) ); + expect( irFnAnonymous ).toHaveLength( 1 ); + expect( irFnAnonymous[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Function declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + const tokenFnNamed = fs.readFileSync( + path.join( __dirname, './fixtures/default-function-named/exports.json' ), + 'utf-8' + ); + const irFnNamed = getIntermediateRepresentation( null, JSON.parse( tokenFnNamed ) ); + expect( irFnNamed[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Function declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + const tokenVariable = fs.readFileSync( + path.join( __dirname, './fixtures/default-variable/exports.json' ), + 'utf-8' + ); + const irVar = getIntermediateRepresentation( null, JSON.parse( tokenVariable ) ); + expect( irVar[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Variable declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + } ); + it( 'named export', function() { + const tokenClass = fs.readFileSync( + path.join( __dirname, './fixtures/named-class/exports.json' ), + 'utf-8' + ); + const irNamedClass = getIntermediateRepresentation( null, JSON.parse( tokenClass ) ); + expect( irNamedClass ).toHaveLength( 1 ); + expect( irNamedClass[ 0 ] ).toEqual( { + path: null, + name: 'MyDeclaration', + description: 'My declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + const tokenFn = fs.readFileSync( + path.join( __dirname, './fixtures/named-function/exports.json' ), + 'utf-8' + ); + const irNamedFn = getIntermediateRepresentation( null, JSON.parse( tokenFn ) ); + expect( irNamedFn ).toHaveLength( 1 ); + expect( irNamedFn[ 0 ] ).toEqual( { + path: null, + name: 'myDeclaration', + description: 'My declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + const tokenVariable = fs.readFileSync( + path.join( __dirname, './fixtures/named-variable/exports.json' ), + 'utf-8' + ); + const irNamedVar = getIntermediateRepresentation( null, JSON.parse( tokenVariable ) ); + expect( irNamedVar ).toHaveLength( 1 ); + expect( irNamedVar[ 0 ] ).toEqual( { + path: null, + name: 'myDeclaration', + description: 'My declaration example.', + tags: [], + lineStart: 4, + lineEnd: 4, + } ); + const tokenVariables = fs.readFileSync( + path.join( __dirname, './fixtures/named-variables/exports.json' ), + 'utf-8' + ); + const irNamedVars = getIntermediateRepresentation( null, JSON.parse( tokenVariables ) ); + expect( irNamedVars ).toHaveLength( 2 ); + expect( irNamedVars[ 0 ] ).toEqual( + { path: null, name: 'firstDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 }, + ); + expect( irNamedVars[ 1 ] ).toEqual( + { path: null, name: 'secondDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 }, + ); + } ); + } ); + + describe( 'JSDoc in same file', function() { + it( 'default export', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/default-identifier/exports.json' ), + 'utf-8' + ); + const ast = fs.readFileSync( + path.join( __dirname, './fixtures/default-identifier/ast.json' ), + 'utf-8' + ); + const irDefaultId = getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) ); + expect( irDefaultId ).toHaveLength( 1 ); + expect( irDefaultId[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Class declaration example.', + tags: [], + lineStart: 6, + lineEnd: 6, + } ); + const namedExport = fs.readFileSync( + path.join( __dirname, './fixtures/default-named-export/exports.json' ), + 'utf-8' + ); + const namedExportAST = fs.readFileSync( + path.join( __dirname, './fixtures/default-named-export/ast.json' ), + 'utf-8' + ); + const irDefaultNamed0 = getIntermediateRepresentation( null, JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ); + expect( irDefaultNamed0 ).toHaveLength( 1 ); + expect( irDefaultNamed0[ 0 ] ).toEqual( + { path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 4, lineEnd: 4 } + ); + const irDefaultNamed1 = getIntermediateRepresentation( null, JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ); + expect( irDefaultNamed1[ 0 ] ).toEqual( + { path: null, name: 'default', description: 'Function declaration example.', tags: [], lineStart: 6, lineEnd: 6 } + ); + } ); + + it( 'named export', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifier/exports.json' ), + 'utf-8' + ); + const ast = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifier/ast.json' ), + 'utf-8' + ); + const irNamedId = getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) ); + expect( irNamedId ).toHaveLength( 1 ); + expect( irNamedId[ 0 ] ).toEqual( { + path: null, + name: 'myDeclaration', + description: 'My declaration example.', + tags: [], + lineStart: 6, + lineEnd: 6, + } ); + const tokenObject = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifier-destructuring/exports.json' ), + 'utf-8' + ); + const astObject = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifier-destructuring/ast.json' ), + 'utf-8' + ); + const irNamedIdDestructuring = getIntermediateRepresentation( null, JSON.parse( tokenObject ), JSON.parse( astObject ) ); + expect( irNamedIdDestructuring ).toHaveLength( 1 ); + expect( irNamedIdDestructuring[ 0 ] ).toEqual( { + path: null, + name: 'myDeclaration', + description: 'My declaration example.', + tags: [], + lineStart: 6, + lineEnd: 6, + } ); + const tokens = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifiers/exports.json' ), + 'utf-8' + ); + const asts = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifiers/ast.json' ), + 'utf-8' + ); + const irIds = getIntermediateRepresentation( null, JSON.parse( tokens ), JSON.parse( asts ) ); + expect( irIds ).toHaveLength( 3 ); + expect( irIds[ 0 ] ).toEqual( + { path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 16, lineEnd: 16 } + ); + expect( irIds[ 1 ] ).toEqual( + { path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 } + ); + expect( irIds[ 2 ] ).toEqual( + { path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 16, lineEnd: 16 } + ); + const foo = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifiers-and-inline/exports.json' ), + 'utf-8' + ); + const bar = fs.readFileSync( + path.join( __dirname, './fixtures/named-identifiers-and-inline/ast.json' ), + 'utf-8' + ); + const irIdInline0 = getIntermediateRepresentation( null, JSON.parse( foo )[ 0 ], JSON.parse( bar ) ); + expect( irIdInline0 ).toHaveLength( 2 ); + expect( irIdInline0[ 0 ] ).toEqual( + { path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 11, lineEnd: 11 } + ); + expect( irIdInline0[ 1 ] ).toEqual( + { path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 11, lineEnd: 11 } + ); + const irIdInline1 = getIntermediateRepresentation( null, JSON.parse( foo )[ 1 ], JSON.parse( bar ) ); + expect( irIdInline1[ 0 ] ).toEqual( + { path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 } + ); + } ); + } ); + + describe( 'JSDoc in module dependency', function() { + it( 'named export', function() { + const tokenImportNamed = fs.readFileSync( + path.join( __dirname, './fixtures/named-import-named/exports.json' ), + 'utf-8' + ); + const getModuleImportNamed = () => JSON.parse( fs.readFileSync( + path.join( __dirname, './fixtures/named-identifiers/ir.json' ), + 'utf-8' + ) ); + const ir = getIntermediateRepresentation( null, JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ); + expect( ir ).toHaveLength( 3 ); + expect( ir[ 0 ] ).toEqual( + { path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 2, lineEnd: 2 } + ); + expect( ir[ 1 ] ).toEqual( + { path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 3, lineEnd: 3 } + ); + expect( ir[ 2 ] ).toEqual( + { path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 4, lineEnd: 4 } + + ); + } ); + + it( 'named default export', function() { + const tokenDefault = fs.readFileSync( + path.join( __dirname, './fixtures/named-default/exports.json' ), + 'utf-8' + ); + const getModule = () => JSON.parse( fs.readFileSync( + path.join( __dirname, './fixtures/named-default/module-ir.json' ), + 'utf-8' + ) ); + const irNamedDefault = getIntermediateRepresentation( null, JSON.parse( tokenDefault ), { body: [] }, getModule ); + expect( irNamedDefault ).toHaveLength( 1 ); + expect( irNamedDefault[ 0 ] ).toEqual( + { path: null, name: 'default', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } + ); + const tokenDefaultExported = fs.readFileSync( + path.join( __dirname, './fixtures/named-default-exported/exports.json' ), + 'utf-8' + ); + const irNamedDefaultExported = getIntermediateRepresentation( null, JSON.parse( tokenDefaultExported ), { body: [] }, getModule ); + expect( irNamedDefaultExported ).toHaveLength( 1 ); + expect( irNamedDefaultExported[ 0 ] ).toEqual( + { path: null, name: 'moduleName', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } + ); + } ); + + it( 'namespace export', function() { + const token = fs.readFileSync( + path.join( __dirname, './fixtures/namespace/exports.json' ), + 'utf-8' + ); + const getModule = () => JSON.parse( fs.readFileSync( + path.join( __dirname, './fixtures/namespace/module-ir.json' ), + 'utf-8' + ) ); + const irNamespace = getIntermediateRepresentation( null, JSON.parse( token ), { body: [] }, getModule ); + expect( irNamespace ).toHaveLength( 3 ); + expect( irNamespace[ 0 ] ).toEqual( + { path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 1, lineEnd: 1 } + ); + expect( irNamespace[ 1 ] ).toEqual( + { path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 1, lineEnd: 1 } + ); + expect( irNamespace[ 2 ] ).toEqual( + { path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 1, lineEnd: 1 } + ); + const tokenCommented = fs.readFileSync( + path.join( __dirname, './fixtures/namespace-commented/exports.json' ), + 'utf-8' + ); + const irNamespaceCommented = getIntermediateRepresentation( null, JSON.parse( tokenCommented ), { body: [] }, getModule ); + expect( irNamespaceCommented ).toHaveLength( 3 ); + expect( irNamespaceCommented[ 0 ] ).toEqual( + { path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 4, lineEnd: 4 } + ); + expect( irNamespaceCommented[ 1 ] ).toEqual( + { path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 4, lineEnd: 4 } + ); + expect( irNamespaceCommented[ 2 ] ).toEqual( + { path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 4, lineEnd: 4 } + ); + } ); + } ); + + describe( 'JSDoc in module dependency through import', function() { + it( 'default export', function() { + const tokenDefault = fs.readFileSync( + path.join( __dirname, './fixtures/default-import-default/exports.json' ), + 'utf-8' + ); + const astDefault = fs.readFileSync( + path.join( __dirname, './fixtures/default-import-default/ast.json' ), + 'utf-8' + ); + const getModuleDefault = () => JSON.parse( fs.readFileSync( + path.join( __dirname, './fixtures/default-import-default/module-ir.json' ), + 'utf-8' + ) ); + const irDefault = getIntermediateRepresentation( null, JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault ); + expect( irDefault ).toHaveLength( 1 ); + expect( irDefault[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Function declaration.', + tags: [], + lineStart: 3, + lineEnd: 3, + } ); + const tokenNamed = fs.readFileSync( + path.join( __dirname, './fixtures/default-import-named/exports.json' ), + 'utf-8' + ); + const astNamed = fs.readFileSync( + path.join( __dirname, './fixtures/default-import-named/ast.json' ), + 'utf-8' + ); + const getModuleNamed = () => JSON.parse( fs.readFileSync( + path.join( __dirname, './fixtures/default-import-named/module-ir.json' ), + 'utf-8' + ) ); + const irNamed = getIntermediateRepresentation( null, JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed ); + expect( irNamed ).toHaveLength( 1 ); + expect( irNamed[ 0 ] ).toEqual( { + path: null, + name: 'default', + description: 'Function declaration.', + tags: [], + lineStart: 3, + lineEnd: 3, + } ); + } ); + + it( 'named export', function() { + const tokenImportNamespace = fs.readFileSync( + path.join( __dirname, './fixtures/named-import-namespace/exports.json' ), + 'utf-8' + ); + const astImportNamespace = fs.readFileSync( + path.join( __dirname, './fixtures/named-import-namespace/ast.json' ), + 'utf-8' + ); + const getModuleImportNamespace = ( filePath ) => { + if ( filePath === './named-import-namespace-module' ) { + return JSON.parse( fs.readFileSync( + path.join( __dirname, './fixtures/named-import-namespace/module-ir.json' ), + 'utf-8' + ) ); + } + return JSON.parse( fs.readFileSync( + path.join( __dirname, './fixtures/default-function/ir.json' ), + 'utf-8' + ) ); + }; + const ir = getIntermediateRepresentation( null, JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ); + expect( ir ).toHaveLength( 1 ); + expect( ir[ 0 ] ).toEqual( + { path: null, name: 'variables', description: 'Undocumented declaration.', tags: [], lineStart: 3, lineEnd: 3 } + ); + } ); + } ); +} ); diff --git a/packages/docgen/src/test/get-jsdoc-from-token.js b/packages/docgen/src/test/get-jsdoc-from-token.js new file mode 100644 index 00000000000000..335d63e7935ac8 --- /dev/null +++ b/packages/docgen/src/test/get-jsdoc-from-token.js @@ -0,0 +1,78 @@ +/** + * Internal dependencies. + */ +const getJSDocFromToken = require( '../get-jsdoc-from-token' ); + +describe( 'JSDoc', () => { + it( 'extracts description and tags', () => { + expect( + getJSDocFromToken( { + leadingComments: [ { + value: '*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n * @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ', + } ], + } ) + ).toEqual( + { + description: 'A function that adds two parameters.', + tags: [ + { + title: 'deprecated', + description: 'Use native addition instead.', + }, + { + title: 'since', + description: 'v2', + }, + { + title: 'see', + description: 'addition', + }, + { + title: 'link', + description: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators', + }, + { + title: 'param', + description: 'The first param to add.', + type: 'number', + name: 'firstParam', + }, + { + title: 'param', + description: 'The second param to add.', + type: 'number', + name: 'secondParam', + }, + { + title: 'example', + description: '```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```', + }, + { + title: 'return', + description: 'The result of adding the two params.', + type: 'number', + }, + ], + } + ); + + expect( + getJSDocFromToken( { + leadingComments: [ { + value: '*\n * Constant to document the meaning of life,\n * the universe and everything else.\n *\n * @type {number}\n ', + } ], + } ) + ).toEqual( + { + description: 'Constant to document the meaning of life,\nthe universe and everything else.', + tags: [ + { + title: 'type', + description: null, + type: 'number', + }, + ], + } + ); + } ); +} ); diff --git a/packages/docgen/src/test/get-type-as-string.js b/packages/docgen/src/test/get-type-as-string.js new file mode 100644 index 00000000000000..6ba09acd33df18 --- /dev/null +++ b/packages/docgen/src/test/get-type-as-string.js @@ -0,0 +1,108 @@ +/** + * Internal dependencies. + */ +const getType = require( '../get-type-as-string' ); + +describe( 'getType from JSDoc', () => { + it( 'NameExpression', () => { + const type = getType( { + title: 'param', + description: 'description', + type: { + type: 'NameExpression', + name: 'Array', + }, + name: 'paramName', + } ); + expect( type ).toBe( 'Array' ); + } ); + + it( 'AllLiteral', () => { + const type = getType( { + title: 'param', + description: 'description', + type: { + type: 'AllLiteral', + }, + name: 'paramName', + } ); + expect( type ).toBe( '*' ); + } ); + + it( 'Applications', () => { + const type = getType( { + title: 'param', + description: 'description', + type: { + type: 'TypeApplication', + expression: { + type: 'NameExpression', + name: 'Array', + }, + applications: [ + { + type: 'NameExpression', + name: 'Object', + }, + { + type: 'NameExpression', + name: 'String', + }, + ], + }, + } ); + expect( type ).toBe( 'Array' ); + } ); + + it( 'NullableType', () => { + const type = getType( { + title: 'param', + description: 'description', + type: { + type: 'NullableType', + expression: { + type: 'NameExpression', + name: 'string', + }, + prefix: true, + }, + name: 'paramName', + } ); + expect( type ).toBe( '?string' ); + } ); + + it( 'RestType', () => { + const type = getType( { + title: 'param', + description: 'description', + type: { + type: 'RestType', + expression: { + type: 'NameExpression', + name: 'Function', + }, + }, + name: 'paramName', + } ); + expect( type ).toBe( '...Function' ); + } ); + + it( 'RestType with UnionType', () => { + const type = getType( { + title: 'param', + description: 'description', + type: { + type: 'RestType', + expression: { + type: 'UnionType', + elements: [ + { type: 'NameExpression', name: 'Object' }, + { type: 'NameExpression', name: 'string' }, + ], + }, + }, + name: 'paramName', + } ); + expect( type ).toBe( '...(Object|string)' ); + } ); +} ); diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index 6743b099d8abb1..4958201be72972 100644 --- a/packages/e2e-test-utils/README.md +++ b/packages/e2e-test-utils/README.md @@ -12,6 +12,8 @@ npm install @wordpress/e2e-test-utils --save-dev ## API + + ### activatePlugin [src/index.js#L1-L1](src/index.js#L1-L1) @@ -76,7 +78,7 @@ Clicks on More Menu item, searches for the button with the text provided and cli ### createEmbeddingMatcher -[src/index.js#L45-L45](src/index.js#L45-L45) +[src/index.js#L46-L46](src/index.js#L46-L46) Creates a function to determine if a request is embedding a certain URL. @@ -90,7 +92,7 @@ Creates a function to determine if a request is embedding a certain URL. ### createJSONResponse -[src/index.js#L45-L45](src/index.js#L45-L45) +[src/index.js#L46-L46](src/index.js#L46-L46) Respond to a request with a JSON response. @@ -129,7 +131,7 @@ Creates new URL by parsing base URL, WPPath and query string. ### createURLMatcher -[src/index.js#L45-L45](src/index.js#L45-L45) +[src/index.js#L46-L46](src/index.js#L46-L46) Creates a function to determine if a request is calling a URL with the substring present. @@ -180,7 +182,7 @@ Verifies that the edit post sidebar is opened, and if it is not, opens it. `Promise` Promise resolving once the edit post sidebar is opened. -### findSidebarPanelWithTitle +### findSidebarPanelToggleButtonWithTitle [src/index.js#L15-L15](src/index.js#L15-L15) @@ -194,10 +196,24 @@ Finds a sidebar panel with the provided title. `?ElementHandle` Object that represents an in-page DOM element. -### getAllBlocks +### findSidebarPanelWithTitle [src/index.js#L16-L16](src/index.js#L16-L16) +Finds the button responsible for toggling the sidebar panel with the provided title. + +**Parameters** + +- **panelTitle** `string`: The name of sidebar panel. + +**Returns** + +`?ElementHandle` Object that represents an in-page DOM element. + +### getAllBlocks + +[src/index.js#L17-L17](src/index.js#L17-L17) + Returns an array with all blocks; Equivalent to calling wp.data.select( 'core/editor' ).getBlocks(); **Returns** @@ -206,7 +222,7 @@ Returns an array with all blocks; Equivalent to calling wp.data.select( 'core/ed ### getAvailableBlockTransforms -[src/index.js#L17-L17](src/index.js#L17-L17) +[src/index.js#L18-L18](src/index.js#L18-L18) Returns an array of strings with all block titles, that the current selected block can be transformed into. @@ -217,7 +233,7 @@ that the current selected block can be transformed into. ### getEditedPostContent -[src/index.js#L18-L18](src/index.js#L18-L18) +[src/index.js#L19-L19](src/index.js#L19-L19) Returns a promise which resolves with the edited post content (HTML string). @@ -227,7 +243,7 @@ Returns a promise which resolves with the edited post content (HTML string). ### hasBlockSwitcher -[src/index.js#L19-L19](src/index.js#L19-L19) +[src/index.js#L20-L20](src/index.js#L20-L20) Returns a boolean indicating if the current selected block has a block switcher or not. @@ -237,7 +253,7 @@ Returns a boolean indicating if the current selected block has a block switcher ### insertBlock -[src/index.js#L20-L20](src/index.js#L20-L20) +[src/index.js#L21-L21](src/index.js#L21-L21) Opens the inserter, searches for the given term, then selects the first result that appears. @@ -249,7 +265,7 @@ result that appears. ### installPlugin -[src/index.js#L21-L21](src/index.js#L21-L21) +[src/index.js#L22-L22](src/index.js#L22-L22) Installs a plugin from the WP.org repository. @@ -260,7 +276,7 @@ Installs a plugin from the WP.org repository. ### isCurrentURL -[src/index.js#L22-L22](src/index.js#L22-L22) +[src/index.js#L23-L23](src/index.js#L23-L23) Checks if current URL is a WordPress path. @@ -275,7 +291,7 @@ Checks if current URL is a WordPress path. ### loginUser -[src/index.js#L23-L23](src/index.js#L23-L23) +[src/index.js#L24-L24](src/index.js#L24-L24) Performs log in with specified username and password. @@ -286,7 +302,7 @@ Performs log in with specified username and password. ### mockOrTransform -[src/index.js#L45-L45](src/index.js#L45-L45) +[src/index.js#L46-L46](src/index.js#L46-L46) Mocks a request with the supplied mock object, or allows it to run with an optional transform, based on the deserialised JSON response for the request. @@ -303,26 +319,26 @@ deserialised JSON response for the request. ### observeFocusLoss -[src/index.js#L24-L24](src/index.js#L24-L24) +[src/index.js#L25-L25](src/index.js#L25-L25) Binds to the document on page load which throws an error if a `focusout` event occurs without a related target (i.e. focus loss). ### openDocumentSettingsSidebar -[src/index.js#L25-L25](src/index.js#L25-L25) +[src/index.js#L26-L26](src/index.js#L26-L26) Clicks on the button in the header which opens Document Settings sidebar when it is closed. ### openPublishPanel -[src/index.js#L26-L26](src/index.js#L26-L26) +[src/index.js#L27-L27](src/index.js#L27-L27) Opens the publish panel. ### pressKeyTimes -[src/index.js#L27-L27](src/index.js#L27-L27) +[src/index.js#L28-L28](src/index.js#L28-L28) Presses the given keyboard key a number of times in sequence. @@ -337,7 +353,7 @@ Presses the given keyboard key a number of times in sequence. ### pressKeyWithModifier -[src/index.js#L28-L28](src/index.js#L28-L28) +[src/index.js#L29-L29](src/index.js#L29-L29) Performs a key press with modifier (Shift, Control, Meta, Alt), where each modifier is normalized to platform-specific modifier. @@ -349,7 +365,7 @@ is normalized to platform-specific modifier. ### publishPost -[src/index.js#L29-L29](src/index.js#L29-L29) +[src/index.js#L30-L30](src/index.js#L30-L30) Publishes the post, resolving once the request is complete (once a notice is displayed). @@ -360,7 +376,7 @@ is displayed). ### publishPostWithPrePublishChecksDisabled -[src/index.js#L30-L30](src/index.js#L30-L30) +[src/index.js#L31-L31](src/index.js#L31-L31) Publishes the post without the pre-publish checks, resolving once the request is complete (once a notice is displayed). @@ -371,7 +387,7 @@ resolving once the request is complete (once a notice is displayed). ### saveDraft -[src/index.js#L31-L31](src/index.js#L31-L31) +[src/index.js#L32-L32](src/index.js#L32-L32) Saves the post as a draft, resolving once the request is complete (once the "Saved" indicator is displayed). @@ -382,7 +398,7 @@ Saves the post as a draft, resolving once the request is complete (once the ### searchForBlock -[src/index.js#L32-L32](src/index.js#L32-L32) +[src/index.js#L33-L33](src/index.js#L33-L33) Search for block in the global inserter @@ -392,7 +408,7 @@ Search for block in the global inserter ### selectBlockByClientId -[src/index.js#L33-L33](src/index.js#L33-L33) +[src/index.js#L34-L34](src/index.js#L34-L34) Given the clientId of a block, selects the block on the editor. @@ -402,7 +418,7 @@ Given the clientId of a block, selects the block on the editor. ### setBrowserViewport -[src/index.js#L34-L34](src/index.js#L34-L34) +[src/index.js#L35-L35](src/index.js#L35-L35) Sets browser viewport to specified type. @@ -412,7 +428,7 @@ Sets browser viewport to specified type. ### setPostContent -[src/index.js#L35-L35](src/index.js#L35-L35) +[src/index.js#L36-L36](src/index.js#L36-L36) Sets code editor content @@ -426,7 +442,7 @@ Sets code editor content ### setUpResponseMocking -[src/index.js#L45-L45](src/index.js#L45-L45) +[src/index.js#L46-L46](src/index.js#L46-L46) Sets up mock checks and responses. Accepts a list of mock settings with the following properties: @@ -457,7 +473,7 @@ If none of the mock settings match the request, the request is allowed to contin ### switchEditorModeTo -[src/index.js#L36-L36](src/index.js#L36-L36) +[src/index.js#L37-L37](src/index.js#L37-L37) Switches editor mode. @@ -467,21 +483,21 @@ Switches editor mode. ### switchUserToAdmin -[src/index.js#L37-L37](src/index.js#L37-L37) +[src/index.js#L38-L38](src/index.js#L38-L38) Switches the current user to the admin user (if the user running the test is not already the admin user). ### switchUserToTest -[src/index.js#L38-L38](src/index.js#L38-L38) +[src/index.js#L39-L39](src/index.js#L39-L39) Switches the current user to whichever user we should be running the tests as (if we're not already that user). ### toggleScreenOption -[src/index.js#L39-L39](src/index.js#L39-L39) +[src/index.js#L40-L40](src/index.js#L40-L40) Toggles the screen option with the given label. @@ -492,7 +508,7 @@ Toggles the screen option with the given label. ### transformBlockTo -[src/index.js#L40-L40](src/index.js#L40-L40) +[src/index.js#L41-L41](src/index.js#L41-L41) Converts editor's block type. @@ -502,7 +518,7 @@ Converts editor's block type. ### uninstallPlugin -[src/index.js#L41-L41](src/index.js#L41-L41) +[src/index.js#L42-L42](src/index.js#L42-L42) Uninstalls a plugin. @@ -512,7 +528,7 @@ Uninstalls a plugin. ### visitAdminPage -[src/index.js#L42-L42](src/index.js#L42-L42) +[src/index.js#L43-L43](src/index.js#L43-L43) Visits admin page; if user is not logged in then it logging in it first, then visits admin page. @@ -523,7 +539,7 @@ Visits admin page; if user is not logged in then it logging in it first, then vi ### waitForWindowDimensions -[src/index.js#L43-L43](src/index.js#L43-L43) +[src/index.js#L44-L44](src/index.js#L44-L44) Function that waits until the page viewport has the required dimensions. It is being used to address a problem where after using setViewport the execution may continue, @@ -535,4 +551,7 @@ without the new dimensions being applied. - **width** `number`: Width of the window. - **height** `height`: Height of the window. + + +

Code is Poetry.

diff --git a/packages/e2e-test-utils/package.json b/packages/e2e-test-utils/package.json index f31d67677475e2..0a6871bff1d76c 100644 --- a/packages/e2e-test-utils/package.json +++ b/packages/e2e-test-utils/package.json @@ -33,11 +33,17 @@ "lodash": "^4.17.11", "node-fetch": "^1.7.3" }, + "devDependencies": { + "@wordpress/docgen": "file:../docgen" + }, "peerDependencies": { "jest": ">=24", "puppeteer": ">=1.6" }, "publishConfig": { "access": "public" + }, + "scripts": { + "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } }