docgen: Omit docblocks with private tag (#15173)

Author: aduth

packages/blocks/README.md

@@ -176,10 +176,6 @@ In the random image block above, we've given the `alt` attribute of the image a
 
 <!-- START TOKEN(Autogenerated API docs) -->
 
-<a name="children" href="#children">#</a> **children**
-
-Undocumented declaration.
-
 <a name="cloneBlock" href="#cloneBlock">#</a> **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.
 
-<a name="node" href="#node">#</a> **node**
-
-Undocumented declaration.
-
 <a name="normalizeIconObject" href="#normalizeIconObject">#</a> **normalizeIconObject**
 
 Function that receives an icon as set by the blocks during the registration

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,

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,

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`.

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;

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 ) {

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;

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
 			);

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 );
 	}
 };