make comments nicer

Author: sarahs

lib/create-tree.js

@@ -6,7 +6,7 @@ const { sortBy } = require('lodash')
 let basePath
 
 module.exports = async function createTree (originalPath, langObj) {
-  // Do not reset this value on recursive runs
+  // Do not reset this value on recursive runs.
   if (!basePath) basePath = originalPath
 
   // On recursive runs, this is processing page.children items in `/<link>` format.
@@ -23,34 +23,34 @@ module.exports = async function createTree (originalPath, langObj) {
   const relativePath = filepath.replace(`${basePath}/`, '')
   const localizedBasePath = path.join(__dirname, '..', langObj.dir, 'content')
 
-  // Initialize the Page! This is where the magic happens (sorry).
+  // Initialize the Page! This is where the file reads happen.
   const page = await Page.init({
     basePath: localizedBasePath,
     relativePath,
     languageCode: langObj.code
   })
 
   if (!page) {
-    // Do not throw an error if early access is not available
+    // Do not throw an error if Early Access is not available.
     if (relativePath.startsWith('early-access')) return
 
     throw Error(`Cannot initialize page for ${filepath}`)
   }
 
-  // Create the root tree object on the first run, and create children recursively
+  // Create the root tree object on the first run, and create children recursively.
   const item = {
     relativePath,
     title: page.shortTitle || page.title,
     page
   }
 
-  // Process frontmatter children recursively
+  // Process frontmatter children recursively.
   if (item.page.children) {
     item.childPages = sortBy(
       (await Promise.all(item.page.children
         .map(async (child) => await createTree(path.join(originalPath, child), langObj))))
         .filter(Boolean),
-      // Sort by the ordered array of children in the frontmatter
+      // Sort by the ordered array of `children` in the frontmatter.
       item.page.children
     )
   }

lib/page-data.js

@@ -5,28 +5,37 @@ const createTree = require('./create-tree')
 const nonEnterpriseDefaultVersion = require('./non-enterprise-default-version')
 const englishPath = path.join(__dirname, '..', 'content')
 
-// This function creates three structures that we need for various purposes:
-// 1. siteTree: A nested object with pages for every language and version:
-//     siteTree[languageCode][version].childPages[<array of pages>].childPages[<array of pages>] (etc...)
-//
-// 2. pageMap: A map of all pages with permalinks as keys for fast lookup.
-//
-// 3. pageList: A simple array of all page objects for fast iterating.
+/**
+ * This function creates three representions of pages we need for different purposes:
+ *
+ * 1. siteTree: A nested object with pages for every language and version, useful for nav because it 
+ * contains parent, child, and sibling relationships:
+ * siteTree[languageCode][version].childPages[<array of pages>].childPages[<array of pages>] (etc...)
+ *
+ * 2. pageMap: A map of all pages with permalinks as keys for fast lookup.
+ *
+ * 3. pageList: A simple array of all page objects for fast iterating.
+*/
 module.exports = async function loadPageData () {
-  // We only need to initialize pages *once per language* since pages don't change per version. So we do that
-  // first since it's the most expensive work. This gets us a nested object with pages attached that we can use
-  // as the basis for the siteTree after we do some versioning.
+  /**
+   * We only need to initialize pages _once per language_ since pages don't change per version. So we do that
+   * first since it's the most expensive work. This gets us a nested object with pages attached that we can use
+   * as the basis for the siteTree after we do some versioning.
+  */
   const rawTree = {}
+
   await Promise.all(Object.values(languages)
     .map(async (langObj) => {
       rawTree[langObj.code] = await createTree(englishPath, langObj)
     }))
 
-  // Now that we have the object of all pages per language, we can walk it for each version and do a couple operations:
-  // 1. Add a versioned href to every item, where the href is the relevant permalink for the current version.
-  //    A) Add an entry for the permalink in the pageMap.
-  // 2. Drop any child pages that are not available in the current version.
-  // Note that order of languages and versions doesn't matter, but order of child page arrays DOES matter (for navigation).
+  /**
+   * Now that we have the object of all pages per language, we can walk it for each version and do a couple operations:
+   * 1. Add a versioned href to every item, where the href is the relevant permalink for the current version.
+   *   A) Add an entry for the permalink in the pageMap.
+   * 2. Drop any child pages that are not available in the current version.
+   * Note that order of languages and versions doesn't matter, but order of child page arrays DOES matter (for navigation).
+  */
   const siteTree = {}
   const pageMap = {}