From d3e3d209a47f615812bea88ce9f6f8baecfc1dc3 Mon Sep 17 00:00:00 2001
From: Frank Li <frankli1@fb.com>
Date: Thu, 3 Aug 2017 11:14:56 -0700
Subject: [PATCH] Add comments for new versioning files

---
 lib/server/versionFallback.js | 17 ++++++++++++++++-
 lib/version.js                |  5 ++++-
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/lib/server/versionFallback.js b/lib/server/versionFallback.js
index 1150f2e890..4683ea7d48 100644
--- a/lib/server/versionFallback.js
+++ b/lib/server/versionFallback.js
@@ -68,7 +68,7 @@ function extractMetadata(content) {
 
 /*****************************************************************/
 
-/* preprocessing */
+// versions is an array of all versions currently in use
 const versions = [];
 const versionFolder = ENABLE_TRANSLATION
   ? CWD + "/versioned_docs/en/"
@@ -83,7 +83,11 @@ files.forEach(file => {
 });
 versions.sort(semver.rcompare);
 
+// available stores doc ids of documents that are available for
+// each version
 const available = {};
+// versionFiles is used to keep track of what file to use with a
+// given version/id of a document
 const versionFiles = {};
 files = glob.sync(versionFolder + "**");
 files.forEach(file => {
@@ -106,6 +110,8 @@ files.forEach(file => {
   versionFiles[version][metadata.original_id] = file;
 });
 
+// returns the version to use for a document based on its id and
+// what the requested version is
 function docVersion(id, req_version) {
   for (let i = 0; i < versions.length; i++) {
     if (semver.gt(versions[i], req_version)) {
@@ -121,6 +127,8 @@ function docVersion(id, req_version) {
   return null;
 }
 
+// returns whether a given file has content that differ from the
+// document with the given id
 function diffLatestDoc(file, id) {
   if (versions.length === 0) {
     return true;
@@ -150,6 +158,8 @@ function diffLatestDoc(file, id) {
   return false;
 }
 
+// return metadata for a versioned file given the file, its version (requested),
+// the version of the file to be used, and its language
 function processVersionMetadata(file, version, useVersion, language) {
   const metadata = extractMetadata(fs.readFileSync(file, "utf8")).metadata;
   metadata.source = "version-" + useVersion + "/" + path.basename(file);
@@ -172,6 +182,7 @@ function processVersionMetadata(file, version, useVersion, language) {
   return metadata;
 }
 
+// return all metadata of versioned documents
 function docData() {
   const files = glob.sync(CWD + "/versioned_docs/**");
 
@@ -203,6 +214,7 @@ function docData() {
   return metadatas;
 }
 
+// return the version of the sidebar to use given a requested version
 function sidebarVersion(req_version) {
   for (let i = 0; i < versions.length; i++) {
     if (semver.gt(versions[i], req_version)) {
@@ -219,6 +231,8 @@ function sidebarVersion(req_version) {
   return null;
 }
 
+// return whether or not the current sidebar.json file differs from the
+// latest versioned one
 function diffLatestSidebar() {
   if (versions.length === 0) {
     return true;
@@ -246,6 +260,7 @@ function diffLatestSidebar() {
   );
 }
 
+// return all versioned sidebar data
 function sidebarData() {
   const allSidebars = {};
 
diff --git a/lib/version.js b/lib/version.js
index 54c8e91999..ebb48b1e40 100644
--- a/lib/version.js
+++ b/lib/version.js
@@ -59,6 +59,7 @@ if (ENABLE_TRANSLATION) {
 }
 mkdirp.sync(versionFolder);
 
+// copy necessary files to new version, changing some of its metadata to reflect the versioning
 let files = glob.sync(CWD + "/../docs/*");
 files.forEach(file => {
   const ext = path.extname(file);
@@ -83,11 +84,13 @@ files.forEach(file => {
   let targetFile =
     CWD + "/versioned_docs/version-" + version + "/" + path.basename(file);
   if (ENABLE_TRANSLATION) {
-    targetFile = CWD + "/versioned_docs/en/version-" + version + "/" + path.basename(file);
+    targetFile =
+      CWD + "/versioned_docs/en/version-" + version + "/" + path.basename(file);
   }
   fs.writeFileSync(targetFile, makeHeader(metadata) + rawContent, "utf8");
 });
 
+// copy sidebar if necessary
 if (versionFallback.diffLatestSidebar()) {
   mkdirp(CWD + "/versioned_sidebars");
   const sidebar = JSON.parse(fs.readFileSync(CWD + "/sidebar.json", "utf8"));