diff --git a/packages/block-library/src/gallery/use-get-media.js b/packages/block-library/src/gallery/use-get-media.js index 1bf33c767a4c64..2d70119e4aa229 100644 --- a/packages/block-library/src/gallery/use-get-media.js +++ b/packages/block-library/src/gallery/use-get-media.js @@ -5,6 +5,14 @@ import { useState } from '@wordpress/element'; import { useSelect } from '@wordpress/data'; import { store as coreStore } from '@wordpress/core-data'; +/** + * Retrieves the extended media info for each gallery image from the store. This is used to + * determine which image size options are available for the current gallery. + * + * @param {Array} innerBlockImages An array of the innerBlock images currently in the gallery. + * + * @return {Array} An array of media info options for each gallery image. + */ export default function useGetMedia( innerBlockImages ) { const [ currentImageMedia, setCurrentImageMedia ] = useState( [] ); diff --git a/packages/block-library/src/gallery/use-get-new-images.js b/packages/block-library/src/gallery/use-get-new-images.js index 67578a5cb9941b..056cf1d2ff6ba1 100644 --- a/packages/block-library/src/gallery/use-get-new-images.js +++ b/packages/block-library/src/gallery/use-get-new-images.js @@ -3,6 +3,16 @@ */ import { useMemo, useState } from '@wordpress/element'; +/** + * Keeps track of images already in the gallery to allow new innerBlocks to be identified. This + * is required so default gallery attributes can be applied without overwriting any custom + * attributes applied to existing images. + * + * @param {Array} images Basic image block data taken from current gallery innerBlock + * @param {Array} imageData The related image data for each of the current gallery images. + * + * @return {Array} An array of any new images that have been added to the gallery. + */ export default function useGetNewImages( images, imageData ) { const [ currentImages, setCurrentImages ] = useState( [] ); diff --git a/packages/block-library/src/gallery/use-image-sizes.js b/packages/block-library/src/gallery/use-image-sizes.js index 5b406adab4cc9a..877bacb67dd137 100644 --- a/packages/block-library/src/gallery/use-image-sizes.js +++ b/packages/block-library/src/gallery/use-image-sizes.js @@ -8,6 +8,16 @@ import { get, some } from 'lodash'; */ import { useMemo } from '@wordpress/element'; +/** + * Calculates the image sizes that are avaible for the current gallery images in order to + * populate the 'Image size' selector. + * + * @param {Array} images Basic image block data taken from current gallery innerBlock + * @param {boolean} isSelected Is the block currently selected in the editor. + * @param {Function} getSettings Block editor store selector. + * + * @return {Array} An array of image size options. + */ export default function useImageSizes( images, isSelected, getSettings ) { return useMemo( () => getImageSizing(), [ images, isSelected ] ); diff --git a/packages/block-library/src/gallery/use-short-code-transform.js b/packages/block-library/src/gallery/use-short-code-transform.js index 3843df9d5a6427..bc251119104083 100644 --- a/packages/block-library/src/gallery/use-short-code-transform.js +++ b/packages/block-library/src/gallery/use-short-code-transform.js @@ -9,6 +9,14 @@ import { every } from 'lodash'; import { useSelect } from '@wordpress/data'; import { store as coreStore } from '@wordpress/core-data'; +/** + * Shortcode transforms don't currently have a tranform method and so can't use a selector to + * retrieve the data for each image being transformer, so this selector handle this post transformation. + * + * @param {Array} shortCodeTransforms An array of image data passed from the shortcode transform. + * + * @return {Array} An array of extended image data objects for each of the shortcode transform images. + */ export default function useShortCodeTransform( shortCodeTransforms ) { const newImageData = useSelect( ( select ) => {