Auto gen initial API docs

WordPress · May 7, 2021 · 9546100 · 9546100
1 parent 13efbb5
commit 9546100
Show file tree

Hide file tree

Showing 2 changed files with 75 additions and 47 deletions.
diff --git a/packages/menus/README.md b/packages/menus/README.md
@@ -16,16 +16,44 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 ## API documentation
 
-<!-- START TOKEN(Autogenerated API docs|src/constants.js) -->
+<!-- START TOKEN(Autogenerated API docs) -->
 
-Content within the HTML comment will be replaced by the generated documentation.
+<a name="convertMenuItemsToBlocks" href="#convertMenuItemsToBlocks">#</a> **convertMenuItemsToBlocks**
 
-<!-- END TOKEN(Autogenerated API docs|src/constants.js) -->`.
+Convert a flat menu item structure to a tree of nested blocks.
 
-<!-- START TOKEN(Autogenerated API docs|src/utils.js) -->
+_Parameters_
 
-Content within the HTML comment will be replaced by the generated documentation.
+-   _menuItems_ `WPNavMenuItem[]`: An array of menu items.
 
-<!-- END TOKEN(Autogenerated API docs|src/utils.js) -->`.
+_Returns_
+
+-   `WPBlock[]`: An array of blocks.
+
+<a name="menuItemToBlockAttributes" href="#menuItemToBlockAttributes">#</a> **menuItemToBlockAttributes**
+
+Convert block attributes to menu item.
+
+Utilised in both block and editor.
+
+_Parameters_
+
+-   _menuItem_ `WPNavMenuItem`: the menu item to be converted to block attributes.
+
+_Returns_
+
+-   `Object`: the block attributes converted from the WPNavMenuItem item.
+
+<a name="NEW_TAB_TARGET_ATTRIBUTE" href="#NEW_TAB_TARGET_ATTRIBUTE">#</a> **NEW_TAB_TARGET_ATTRIBUTE**
+
+The string identifier for the menu item's "target" attribute indicating
+the menu item link should open in a new tab.
+
+_Type_
+
+-   `string`
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
 
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/menus/src/utils.js b/packages/menus/src/utils.js
@@ -30,9 +30,9 @@ import { NEW_TAB_TARGET_ATTRIBUTE } from './constants';
  */
 
 /**
- * Convert a flat menu item structure to a nested blocks structure.
+ * Convert a flat menu item structure to a tree of nested blocks.
  *
- * @param {Object[]} menuItems An array of menu items.
+ * @param {WPNavMenuItem[]} menuItems An array of menu items.
  *
  * @return {WPBlock[]} An array of blocks.
  */
@@ -45,44 +45,6 @@ export function convertMenuItemsToBlocks( menuItems ) {
 	return mapMenuItemsToBlocks( menuTree );
 }
 
-/**
- * Creates a nested, hierarchical tree representation from unstructured data that
- * has an inherent relationship defined between individual items.
- *
- * For example, by default, each element in the dataset should have an `id` and
- * `parent` property where the `parent` property indicates a relationship between
- * the current item and another item with a matching `id` properties.
- *
- * This is useful for building linked lists of data from flat data structures.
- *
- * @param {Array} dataset linked data to be rearranged into a hierarchical tree based on relational fields.
- * @param {string} id the property which uniquely identifies each entry within the array.
- * @param {*} relation the property which identifies how the current item is related to other items in the data (if at all).
- * @return {Array} a nested array of parent/child relationships
- */
-export function createDataTree( dataset, id = 'id', relation = 'parent' ) {
-	const hashTable = Object.create( null );
-	const dataTree = [];
-
-	for ( const data of dataset ) {
-		hashTable[ data[ id ] ] = {
-			...data,
-			children: [],
-		};
-	}
-	for ( const data of dataset ) {
-		if ( data[ relation ] ) {
-			hashTable[ data[ relation ] ].children.push(
-				hashTable[ data[ id ] ]
-			);
-		} else {
-			dataTree.push( hashTable[ data[ id ] ] );
-		}
-	}
-
-	return dataTree;
-}
-
 /**
  * Convert block attributes to menu item.
  *
@@ -146,7 +108,7 @@ export const menuItemToBlockAttributes = ( {
 /**
  * A recursive function that maps menu item nodes to blocks.
  *
- * @param {Object[]} menuItems An array of menu items.
+ * @param {WPNavMenuItem[]} menuItems An array of menu items.
  * @return {WPBlock[]} An array of blocks.
  */
 export default function mapMenuItemsToBlocks( menuItems ) {
@@ -172,3 +134,41 @@ export default function mapMenuItemsToBlocks( menuItems ) {
 		return createBlock( 'core/navigation-link', attributes, innerBlocks );
 	} );
 }
+
+/**
+ * Creates a nested, hierarchical tree representation from unstructured data that
+ * has an inherent relationship defined between individual items.
+ *
+ * For example, by default, each element in the dataset should have an `id` and
+ * `parent` property where the `parent` property indicates a relationship between
+ * the current item and another item with a matching `id` properties.
+ *
+ * This is useful for building linked lists of data from flat data structures.
+ *
+ * @param {Array} dataset linked data to be rearranged into a hierarchical tree based on relational fields.
+ * @param {string} id the property which uniquely identifies each entry within the array.
+ * @param {*} relation the property which identifies how the current item is related to other items in the data (if at all).
+ * @return {Array} a nested array of parent/child relationships
+ */
+function createDataTree( dataset, id = 'id', relation = 'parent' ) {
+	const hashTable = Object.create( null );
+	const dataTree = [];
+
+	for ( const data of dataset ) {
+		hashTable[ data[ id ] ] = {
+			...data,
+			children: [],
+		};
+	}
+	for ( const data of dataset ) {
+		if ( data[ relation ] ) {
+			hashTable[ data[ relation ] ].children.push(
+				hashTable[ data[ id ] ]
+			);
+		} else {
+			dataTree.push( hashTable[ data[ id ] ] );
+		}
+	}
+
+	return dataTree;
+}