Fix JSDoc comments for file helpers

alphagov · Oct 12, 2022 · f9454c3 · f9454c3
1 parent dfac6c6
commit f9454c3
Showing 1 changed file with 28 additions and 5 deletions.
diff --git a/lib/file-helper.js b/lib/file-helper.js
@@ -9,7 +9,7 @@ const configPaths = require('../config/paths.js')
  * Directory listing for path
  *
  * @param {string} directoryPath
- * @returns {Promise<Map<basename, { path: string; stats: import('fs').Stats }>>} Directory listing
+ * @returns {Promise<DirectoryListing>} Directory listing
  */
 const getListing = async (directoryPath) => {
   const basenames = await readdir(directoryPath)
@@ -32,7 +32,7 @@ const getListing = async (directoryPath) => {
  * Directory listing (directories only)
  *
  * @param {string} directoryPath
- * @returns {Promise<Map<dirname, { path: string; stats: import('fs').Stats }>>} Directory entries
+ * @returns {Promise<DirectoryListing>} Directory entries
  */
 const getDirectories = async (directoryPath) => {
   const listing = await getListing(directoryPath)
@@ -48,7 +48,7 @@ const getDirectories = async (directoryPath) => {
  * Directory listing (files only)
  *
  * @param {string} directoryPath
- * @returns {Promise<Map<filename, { path: string; stats: import('fs').Stats }>>} File entries
+ * @returns {Promise<DirectoryListing>} File entries
  */
 const getFiles = async (directoryPath) => {
   const listing = await getListing(directoryPath)
@@ -64,7 +64,7 @@ const getFiles = async (directoryPath) => {
  * Directory listing (files, grouped by directory)
  *
  * @param {string} directoryPath
- * @returns {Promise<Map<dirname, Map<filename, { path: string; stats: import('fs').Stats }>>>} File entries by directory
+ * @returns {Promise<Map<string, DirectoryListing>>} File entries by directory
  */
 const getFilesByDirectory = async (directoryPath) => {
   const directories = await getDirectories(directoryPath)
@@ -110,7 +110,7 @@ const getComponentsData = async () => {
 /**
  * Load all full page examples' front matter
  *
- * @returns {Promise<{ name: string; scenario?: string; notes?: string }[]>} Full page examples
+ * @returns {Promise<FullPageExample[]>} Full page examples
  */
 const getFullPageExamples = async () => {
   const directories = await getDirectories(configPaths.fullPageExamples)
@@ -145,6 +145,20 @@ module.exports = {
   getListing
 }
 
+/**
+ * Directory listing
+ *
+ * @typedef {Map<string, { path: string; stats: import('fs').Stats }>} DirectoryListing
+ */
+
+/**
+ * Directory listing entry
+ *
+ * @typedef {object} DirectoryListingEntry
+ * @property {string} path - Relative path to file or directory
+ * @property {import('fs').Stats} stats - Information about a file or directory
+ */
+
 /**
  * Component data from YAML
  *
@@ -155,3 +169,12 @@ module.exports = {
  * @property {string} [previewLayout] - Nunjucks layout for component preview
  * @property {string} [accessibilityCriteria] - Accessibility criteria
  */
+
+/**
+ * Full page example from front matter
+ *
+ * @typedef {object} FullPageExample
+ * @property {string} name - Example name
+ * @property {string} [scenario] - Description explaining the example
+ * @property {string} [notes] - Additional notes about the example
+ */