diff --git a/packages/blocks/README.md b/packages/blocks/README.md index e6b041aa7fb576..03442bbe5e7297 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -176,10 +176,6 @@ In the random image block above, we've given the `alt` attribute of the image a -# **children** - -Undocumented declaration. - # **cloneBlock** Given a block object, returns a copy of the block object, optionally merging @@ -536,10 +532,6 @@ _Returns_ - `boolean`: True if the parameter is a valid icon and false otherwise. -# **node** - -Undocumented declaration. - # **normalizeIconObject** Function that receives an icon as set by the blocks during the registration diff --git a/packages/blocks/src/api/children.js b/packages/blocks/src/api/children.js index c31064f5e22a92..7cf70d2da78151 100644 --- a/packages/blocks/src/api/children.js +++ b/packages/blocks/src/api/children.js @@ -138,6 +138,17 @@ export function matcher( selector ) { }; } +/** + * Object of utility functions used in managing block attribute values of + * source `children`. + * + * @see https://github.com/WordPress/gutenberg/pull/10439 + * + * @deprecated since 4.0. The `children` source should not be used, and can be + * replaced by the `html` source. + * + * @private + */ export default { concat, getChildrenArray, diff --git a/packages/blocks/src/api/node.js b/packages/blocks/src/api/node.js index abcacf2b41c0c8..075715f1d84c4a 100644 --- a/packages/blocks/src/api/node.js +++ b/packages/blocks/src/api/node.js @@ -118,6 +118,17 @@ export function matcher( selector ) { }; } +/** + * Object of utility functions used in managing block attribute values of + * source `node`. + * + * @see https://github.com/WordPress/gutenberg/pull/10439 + * + * @deprecated since 4.0. The `node` source should not be used, and can be + * replaced by the `html` source. + * + * @private + */ export default { isNodeOfType, fromDOM, diff --git a/packages/docgen/CHANGELOG.md b/packages/docgen/CHANGELOG.md index ebd35131a443d0..943d22d361ba0d 100644 --- a/packages/docgen/CHANGELOG.md +++ b/packages/docgen/CHANGELOG.md @@ -1,5 +1,9 @@ ## Master +### Enhancements + +- Docblocks including a `@private` tag will be omitted from the generated result. + ### Internal - Remove unneccessary argument from an instance of `Array#pop`. diff --git a/packages/docgen/src/get-symbol-tags-by-name.js b/packages/docgen/src/get-symbol-tags-by-name.js new file mode 100644 index 00000000000000..194077cf11c9e4 --- /dev/null +++ b/packages/docgen/src/get-symbol-tags-by-name.js @@ -0,0 +1,16 @@ +/** + * Given a symbol object and tag name(s), returns tag objects from the symbol + * matching the given name. + * + * @param {Object} symbol Symbol object. + * @param {...string} names Names of tags to return. + * + * @return {Object[]} Matching tag objects. + */ +function getSymbolTagsByName( symbol, ...names ) { + return symbol.tags.filter( ( tag ) => { + return names.some( ( name ) => name === tag.title ); + } ); +} + +module.exports = getSymbolTagsByName; diff --git a/packages/docgen/src/index.js b/packages/docgen/src/index.js index 8b03dfe9bfafcd..475a458955d070 100644 --- a/packages/docgen/src/index.js +++ b/packages/docgen/src/index.js @@ -10,6 +10,7 @@ const { last } = require( 'lodash' ); */ const engine = require( './engine' ); const defaultMarkdownFormatter = require( './markdown' ); +const isSymbolPrivate = require( './is-symbol-private' ); /** * Helpers functions. @@ -102,7 +103,17 @@ module.exports = function( sourceFile, options ) { // Process const result = processFile( processDir, sourceFile ); - const filteredIr = result.ir.filter( ( { name } ) => options.ignore ? ! name.match( options.ignore ) : true ); + const filteredIR = result.ir.filter( ( symbol ) => { + if ( isSymbolPrivate( symbol ) ) { + return false; + } + + if ( options.ignore ) { + return ! symbol.name.match( options.ignore ); + } + + return true; + } ); // Ouput if ( result === undefined ) { @@ -113,9 +124,9 @@ module.exports = function( sourceFile, options ) { } if ( options.formatter ) { - runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr, 'API' ); + runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIR, 'API' ); } else { - defaultMarkdownFormatter( options, processDir, doc, filteredIr, 'API' ); + defaultMarkdownFormatter( options, processDir, doc, filteredIR, 'API' ); } if ( debugMode ) { diff --git a/packages/docgen/src/is-symbol-private.js b/packages/docgen/src/is-symbol-private.js new file mode 100644 index 00000000000000..a26974f3d42559 --- /dev/null +++ b/packages/docgen/src/is-symbol-private.js @@ -0,0 +1,16 @@ +/** + * Internal dependencies + */ +const getSymbolTagsByName = require( './get-symbol-tags-by-name' ); + +/** + * Returns true if, given a symbol object, it contains a @private tag, or false + * otherwise. + * + * @param {Object} symbol Symbol object. + * + * @return {boolean} Whether symbol is private. + */ +const isSymbolPrivate = ( symbol ) => getSymbolTagsByName( symbol, 'private' ).length > 0; + +module.exports = isSymbolPrivate; diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js index 0912b7d0343168..eaec51925f3062 100644 --- a/packages/docgen/src/markdown/formatter.js +++ b/packages/docgen/src/markdown/formatter.js @@ -1,4 +1,7 @@ -const getTagsByName = ( tags, ...names ) => tags.filter( ( tag ) => names.some( ( name ) => name === tag.title ) ); +/** + * Internal dependencies + */ +const getSymbolTagsByName = require( '../get-symbol-tags-by-name' ); const cleanSpaces = ( paragraph ) => paragraph ? @@ -57,7 +60,7 @@ const getSymbolHeading = ( text ) => { }; module.exports = function( rootDir, docPath, symbols, headingTitle, headingStartIndex ) { - const docs = [ ]; + const docs = []; let headingIndex = headingStartIndex || 1; if ( headingTitle ) { docs.push( getHeading( headingIndex, `${ headingTitle }` ) ); @@ -79,30 +82,30 @@ module.exports = function( rootDir, docPath, symbols, headingTitle, headingStart if ( symbols && symbols.length > 0 ) { symbols.forEach( ( symbol ) => { docs.push( getSymbolHeading( symbol.name ) ); - formatDeprecated( getTagsByName( symbol.tags, 'deprecated' ), docs ); + formatDeprecated( getSymbolTagsByName( symbol, 'deprecated' ), docs ); formatDescription( symbol.description, docs ); formatTag( 'Related', - getTagsByName( symbol.tags, 'see', 'link' ), + getSymbolTagsByName( symbol, 'see', 'link' ), ( tag ) => `\n- ${ tag.description }`, docs ); - formatExamples( getTagsByName( symbol.tags, 'example' ), docs ); + formatExamples( getSymbolTagsByName( symbol, 'example' ), docs ); formatTag( 'Type', - getTagsByName( symbol.tags, 'type' ), + getSymbolTagsByName( symbol, 'type' ), ( tag ) => `\n- \`${ tag.type }\` ${ cleanSpaces( tag.description ) }`, docs ); formatTag( 'Parameters', - getTagsByName( symbol.tags, 'param' ), + getSymbolTagsByName( symbol, 'param' ), ( tag ) => `\n- *${ tag.name }* \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, docs ); formatTag( 'Returns', - getTagsByName( symbol.tags, 'return' ), + getSymbolTagsByName( symbol, 'return' ), ( tag ) => `\n- \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`, docs ); diff --git a/packages/docgen/src/markdown/index.js b/packages/docgen/src/markdown/index.js index 499e211e1873a4..b73041903bc7a2 100644 --- a/packages/docgen/src/markdown/index.js +++ b/packages/docgen/src/markdown/index.js @@ -24,10 +24,10 @@ const appendOrEmbedContents = ( { options, newContents } ) => { }; }; -module.exports = function( options, processDir, doc, filteredIr, headingTitle ) { +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 ) ); + const newContents = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIR, null ) ); remark() .use( { settings: { commonmark: true } } ) .use( appendOrEmbedContents, { options, newContents } ) @@ -38,7 +38,7 @@ module.exports = function( options, processDir, doc, filteredIr, headingTitle ) fs.writeFileSync( doc, file ); } ); } else { - const output = formatter( processDir, doc, filteredIr, headingTitle ); + const output = formatter( processDir, doc, filteredIR, headingTitle ); fs.writeFileSync( doc, output ); } }; diff --git a/packages/docgen/src/test/fixtures/markdown/code.js b/packages/docgen/src/test/fixtures/markdown/code.js deleted file mode 100644 index 8d4261e0f63289..00000000000000 --- a/packages/docgen/src/test/fixtures/markdown/code.js +++ /dev/null @@ -1,24 +0,0 @@ -/** - * 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 deleted file mode 100644 index 12baa9046d0280..00000000000000 --- a/packages/docgen/src/test/fixtures/markdown/docs.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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.