From 43ef3c8142bb94b85959d546bb3599b1485b551b Mon Sep 17 00:00:00 2001
From: Frank Li <frankli1@fb.com>
Date: Tue, 15 Aug 2017 16:55:38 -0700
Subject: [PATCH] Add comments

---
 lib/build-files.js           |  1 +
 lib/copy-examples.js         |  4 +++
 lib/core/BlogPageLayout.js   |  1 +
 lib/core/BlogPost.js         |  1 +
 lib/core/BlogPostLayout.js   |  1 +
 lib/core/CompLibrary.js      |  1 +
 lib/core/Doc.js              |  1 +
 lib/core/DocsLayout.js       |  1 +
 lib/core/Head.js             |  1 +
 lib/core/Marked.js           |  2 ++
 lib/core/Prism.js            |  2 ++
 lib/core/Site.js             | 17 +-----------
 lib/core/nav/HeaderNav.js    | 16 ++++++++---
 lib/core/nav/SideNav.js      |  3 +++
 lib/publish-gh-pages.js      |  2 ++
 lib/server/generate.js       | 52 ++++++++++++++++++++++--------------
 lib/server/readCategories.js |  2 ++
 lib/server/readMetadata.js   |  9 +++++--
 lib/server/server.js         | 39 ++++++++++++++++-----------
 lib/server/translation.js    | 11 ++++++++
 lib/start-server.js          |  1 +
 lib/write-translations.js    |  8 +++---
 22 files changed, 114 insertions(+), 62 deletions(-)

diff --git a/lib/build-files.js b/lib/build-files.js
index fdd692161f..8dd2e5c755 100755
--- a/lib/build-files.js
+++ b/lib/build-files.js
@@ -28,5 +28,6 @@ if (!fs.existsSync(CWD + "/siteConfig.js")) {
   process.exit(1);
 }
 
+// generate all static html files
 const generate = require("./server/generate.js");
 generate();
diff --git a/lib/copy-examples.js b/lib/copy-examples.js
index 792740f2ce..3a9a23e097 100755
--- a/lib/copy-examples.js
+++ b/lib/copy-examples.js
@@ -26,7 +26,10 @@ program
   .parse(process.argv);
 
 const outerFolder = path.basename(path.dirname(CWD));
+
+// handles cases where feature is "translations", "versions" or neither/not present
 if (feature === "translations") {
+  // copy files for translations
   const folder = path.join(__dirname, "..", "examples", "translations");
   if (fs.existsSync(CWD + "/../crowdin.yaml")) {
     console.log(
@@ -74,6 +77,7 @@ if (feature === "translations") {
     }
   });
 } else if (feature === "versions") {
+  // copy files for versions
   const folder = path.join(__dirname, "..", "examples", "versions");
   let files = glob.sync(folder + "/**/*");
   files.forEach(file => {
diff --git a/lib/core/BlogPageLayout.js b/lib/core/BlogPageLayout.js
index 6bfebc6b25..a5fbc271dd 100644
--- a/lib/core/BlogPageLayout.js
+++ b/lib/core/BlogPageLayout.js
@@ -14,6 +14,7 @@ const MetadataBlog = require("./MetadataBlog.js");
 const React = require("react");
 const Site = require("./Site.js");
 
+// used to generate entire blog pages, i.e. collection of truncated blog posts
 const BlogPageLayout = React.createClass({
   getPageURL(page) {
     let url = this.props.config.baseUrl + "blog/";
diff --git a/lib/core/BlogPost.js b/lib/core/BlogPost.js
index 71da9c3e3c..19ed673bdf 100644
--- a/lib/core/BlogPost.js
+++ b/lib/core/BlogPost.js
@@ -10,6 +10,7 @@
 const Marked = require("./Marked.js");
 const React = require("react");
 
+// inner blog component for the article itself, without sidebar/header/footer
 class BlogPost extends React.Component {
   renderContent() {
     let content = this.props.content;
diff --git a/lib/core/BlogPostLayout.js b/lib/core/BlogPostLayout.js
index 389a00d462..dcb1f4d01f 100644
--- a/lib/core/BlogPostLayout.js
+++ b/lib/core/BlogPostLayout.js
@@ -13,6 +13,7 @@ const BlogSidebar = require("./BlogSidebar.js");
 const Container = require("./Container.js");
 const Site = require("./Site.js");
 
+// used for entire blog posts, i.e., each written blog article with sidebar with site header/footer
 class BlogPostLayout extends React.Component {
   render() {
     return (
diff --git a/lib/core/CompLibrary.js b/lib/core/CompLibrary.js
index c138962b88..33e730331d 100644
--- a/lib/core/CompLibrary.js
+++ b/lib/core/CompLibrary.js
@@ -11,6 +11,7 @@ const Marked = require("./Marked.js");
 const Container = require("./Container.js");
 const GridBlock = require("./GridBlock.js");
 
+// collection of other components to provide to users
 module.exports = {
   Marked: Marked,
   Container: Container,
diff --git a/lib/core/Doc.js b/lib/core/Doc.js
index 2b071f53cb..af57066436 100644
--- a/lib/core/Doc.js
+++ b/lib/core/Doc.js
@@ -10,6 +10,7 @@
 const React = require("react");
 const Marked = require("./Marked.js");
 
+// inner doc component for article itself
 class Doc extends React.Component {
   render() {
     let editLink =
diff --git a/lib/core/DocsLayout.js b/lib/core/DocsLayout.js
index 4622892076..81911ace1b 100644
--- a/lib/core/DocsLayout.js
+++ b/lib/core/DocsLayout.js
@@ -14,6 +14,7 @@ const DocsSidebar = require("./DocsSidebar.js");
 const Site = require("./Site.js");
 const translation = require("../server/translation.js");
 
+// component used to generate whole webpage for docs, including sidebar/header/footer
 class DocsLayout extends React.Component {
   render() {
     const metadata = this.props.metadata;
diff --git a/lib/core/Head.js b/lib/core/Head.js
index 87be676ed4..587ebc7264 100644
--- a/lib/core/Head.js
+++ b/lib/core/Head.js
@@ -9,6 +9,7 @@
 
 const React = require("react");
 
+// html head for each page
 class Head extends React.Component {
   render() {
     return (
diff --git a/lib/core/Marked.js b/lib/core/Marked.js
index bb65d2488d..5ea91b2ec7 100644
--- a/lib/core/Marked.js
+++ b/lib/core/Marked.js
@@ -7,6 +7,8 @@
  * of patent rights can be found in the PATENTS file in the same directory.
  */
 
+/* Marked component is used to parse markdown to html */
+
 const React = require("react");
 const Prism = require("./Prism.js");
 const Header = require("./Header.js");
diff --git a/lib/core/Prism.js b/lib/core/Prism.js
index 24743a082d..3030745466 100644
--- a/lib/core/Prism.js
+++ b/lib/core/Prism.js
@@ -7,6 +7,8 @@
  * of patent rights can be found in the PATENTS file in the same directory.
  */
 
+/* Prism is used by Marked to do code syntas highlighting */
+
 const React = require("react");
 
 /**
diff --git a/lib/core/Site.js b/lib/core/Site.js
index dd111eef5e..fd9fee7947 100644
--- a/lib/core/Site.js
+++ b/lib/core/Site.js
@@ -16,23 +16,8 @@ const translation = require("../server/translation.js");
 
 const CWD = process.cwd();
 
+// Component used to provide same head, header, footer, other scripts to all pages
 class Site extends React.Component {
-  /*
-  goes in body after navPusher
-
-  <script
-    dangerouslySetInnerHTML={{
-      __html: `
-   
-    !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)
-    ){js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";
-    fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
-  `,
-    }}
-  />
-
-  */
-
   render() {
     const tagline = translation[this.props.language]
       ? translation[this.props.language]["localized-strings"].tagline
diff --git a/lib/core/nav/HeaderNav.js b/lib/core/nav/HeaderNav.js
index f1c55a0fdd..506876c42f 100644
--- a/lib/core/nav/HeaderNav.js
+++ b/lib/core/nav/HeaderNav.js
@@ -23,11 +23,12 @@ if (ENABLE_VERSIONING) {
 require("../../server/readMetadata.js").generateDocsMetadata();
 const Metadata = require("../metadata.js");
 
+// language dropdown nav item for when translations are enabled
 class LanguageDropDown extends React.Component {
   render() {
     const enabledLanguages = [];
     let currentLanguage = "English";
-
+    // add all enabled languages to dropdown
     translation["languages"].map(lang => {
       if (lang.tag == this.props.language) {
         currentLanguage = lang.name;
@@ -43,11 +44,11 @@ class LanguageDropDown extends React.Component {
         </li>
       );
     });
-
+    // if no languages are enabled besides English, return null
     if (enabledLanguages.length < 1) {
       return null;
     }
-
+    // add Crowdin project recruiting link
     if (siteConfig.recruitingLink) {
       enabledLanguages.push(
         <li key="recruiting">
@@ -94,6 +95,7 @@ class LanguageDropDown extends React.Component {
   }
 }
 
+// header navbar used by all pages generated with docusaurus
 class HeaderNav extends React.Component {
   constructor() {
     super();
@@ -101,10 +103,11 @@ class HeaderNav extends React.Component {
       slideoutActive: false
     };
   }
-
+  // function to generate each header link, used with each object in siteConfig.headerLinks
   makeLinks(link) {
     let href;
     if (link.search && this.props.config.algolia) {
+      // return algolia search bar
       return (
         <li className="navSearchWrapper reactNavSearchWrapper">
           <input id="search_input_react" type="text" placeholder="Search" />
@@ -112,12 +115,14 @@ class HeaderNav extends React.Component {
       );
     } else if (link.languages) {
       return (
+        // return language dropdown
         <LanguageDropDown
           baseUrl={this.props.baseUrl}
           language={this.props.language}
         />
       );
     } else if (link.doc) {
+      // set link to document with current page's language/version
       let id;
       if (!ENABLE_VERSIONING || this.props.version === "next") {
         id = this.props.language + "-" + link.doc;
@@ -137,6 +142,7 @@ class HeaderNav extends React.Component {
       }
       href = this.props.config.baseUrl + Metadata[id].permalink;
     } else if (link.page) {
+      // set link to page with current page's language if appropriate
       if (fs.existsSync(CWD + "/pages/en/" + link.page + ".js")) {
         href =
           siteConfig.baseUrl + this.props.language + "/" + link.page + ".html";
@@ -144,8 +150,10 @@ class HeaderNav extends React.Component {
         href = siteConfig.baseUrl + link.page + ".html";
       }
     } else if (link.href) {
+      // set link to specified href
       href = link.href;
     } else if (link.blog) {
+      // set link to blog url
       href = this.props.baseUrl + "blog";
     }
     return (
diff --git a/lib/core/nav/SideNav.js b/lib/core/nav/SideNav.js
index c6384bb4f7..96ffdf6648 100644
--- a/lib/core/nav/SideNav.js
+++ b/lib/core/nav/SideNav.js
@@ -61,6 +61,7 @@ class SideNav extends React.Component {
       </div>
     );
   }
+  // return appropriately translated category string
   getLocalizedCategoryString(category) {
     let categoryString = translation[this.props.language]
       ? translation[this.props.language]["localized-strings"][category] ||
@@ -68,6 +69,7 @@ class SideNav extends React.Component {
       : category;
     return categoryString;
   }
+  // return appropriately translated label to use for doc/blog in sidebar
   getLocalizedString(metadata) {
     let localizedString;
     const i18n = translation[this.props.language];
@@ -85,6 +87,7 @@ class SideNav extends React.Component {
     }
     return localizedString;
   }
+  // return link to doc in sidebar
   getLink(metadata) {
     if (metadata.permalink) {
       if (metadata.permalink.match(/^https?:/)) {
diff --git a/lib/publish-gh-pages.js b/lib/publish-gh-pages.js
index bd4604350c..435c7ba555 100755
--- a/lib/publish-gh-pages.js
+++ b/lib/publish-gh-pages.js
@@ -18,6 +18,8 @@ const CIRCLE_PROJECT_REPONAME = process.env.CIRCLE_PROJECT_REPONAME;
 const CI_PULL_REQUEST = process.env.CI_PULL_REQUEST;
 const remoteBranch = `https://${GIT_USER}@github.com/${CIRCLE_PROJECT_USERNAME}/${CIRCLE_PROJECT_REPONAME}.git`;
 
+// build static html files, then push to gh-pages branch of specified repo
+
 if (!shell.which("git")) {
   shell.echo("Sorry, this script requires git");
   shell.exit(1);
diff --git a/lib/server/generate.js b/lib/server/generate.js
index 3405bacd27..53a4b9601d 100644
--- a/lib/server/generate.js
+++ b/lib/server/generate.js
@@ -38,7 +38,7 @@ function execute() {
       }
     ];
   }
-
+  // create the folder path for a file if it does not exist, then write the file
   function writeFileAndCreateFolder(file, content) {
     mkdirp.sync(file.replace(new RegExp("/[^/]*$"), ""));
 
@@ -47,6 +47,8 @@ function execute() {
 
   const TABLE_OF_CONTENTS_TOKEN = "<AUTOGENERATED_TABLE_OF_CONTENTS>";
 
+  // takes the content of a doc article and returns the content with a table of
+  // contents inserted
   const insertTableOfContents = rawContent => {
     const regexp = /\n###\s+(`.*`.*)\n/g;
     let match;
@@ -62,6 +64,8 @@ function execute() {
     return rawContent.replace(TABLE_OF_CONTENTS_TOKEN, tableOfContents);
   };
 
+  // returns true if a file should be excluded from concatentation to
+  // default Docusaurus styles
   function isSeparateCss(file) {
     if (!siteConfig.separateCss) {
       return false;
@@ -76,6 +80,7 @@ function execute() {
 
   console.log("generate.js triggered...");
 
+  // array of tags of enabled languages
   const enabledLanguages = [];
   languages.filter(lang => lang.enabled).map(lang => {
     enabledLanguages.push(lang.tag);
@@ -84,6 +89,8 @@ function execute() {
   readMetadata.generateDocsMetadata();
   const Metadata = require("../core/metadata.js");
 
+  // mdToHtml is a map from a markdown file name to its html link, used to
+  // change relative markdown links that work on GitHub into actual site links
   const mdToHtml = {};
   Object.keys(Metadata).forEach(id => {
     const metadata = Metadata[id];
@@ -104,10 +111,10 @@ function execute() {
 
   fs.removeSync(CWD + "/build");
 
-  // create html files for all docs
+  // create html files for all docs by going through all doc ids
   Object.keys(Metadata).forEach(id => {
     const metadata = Metadata[id];
-
+    // determine what file to use according to its id
     let file;
     if (metadata.original_id) {
       if (ENABLE_TRANSLATION && metadata.language !== "en") {
@@ -134,7 +141,7 @@ function execute() {
 
     const language = metadata.language;
 
-    /* generate table of contents if appropriate */
+    // generate table of contents if appropriate
     if (rawContent && rawContent.indexOf(TABLE_OF_CONTENTS_TOKEN) != -1) {
       rawContent = insertTableOfContents(rawContent);
     }
@@ -146,7 +153,7 @@ function execute() {
       )[0];
     }
 
-    /* replace any links to markdown files to their website html links */
+    // replace any links to markdown files to their website html links
     Object.keys(mdToHtml).forEach(function(key, index) {
       let link = mdToHtml[key];
       link = link.replace("/en/", "/" + language + "/");
@@ -158,7 +165,8 @@ function execute() {
       );
       rawContent = rawContent.replace(new RegExp(key, "g"), link);
     });
-
+    
+    // replace any relative links to static assets to absolute links
     rawContent = rawContent.replace(
       /\]\(assets\//g,
       "](" + siteConfig.baseUrl + "docs/assets/"
@@ -176,7 +184,7 @@ function execute() {
     writeFileAndCreateFolder(targetFile, str);
   });
 
-  /* copy docs assets if they exist */
+  // copy docs assets if they exist
   if (fs.existsSync(CWD + "/../docs/assets")) {
     fs.copySync(
       CWD + "/../docs/assets",
@@ -184,7 +192,7 @@ function execute() {
     );
   }
 
-  // create html files for all blog posts
+  // create html files for all blog posts (each article)
   if (fs.existsSync(__dirname + "../core/MetadataBlog.js")) {
     fs.removeSync(__dirname + "../core/MetadataBlog.js");
   }
@@ -199,7 +207,7 @@ function execute() {
       return;
     }
 
-    /* convert filename ot use slashes */
+    // convert filename to use slashes
     const filePath = path
       .basename(file)
       .replace("-", "/")
@@ -233,7 +241,7 @@ function execute() {
       CWD + "/build/" + siteConfig.projectName + "/blog/" + filePath;
     writeFileAndCreateFolder(targetFile, str);
   });
-  // create html files for all blog pages
+  // create html files for all blog pages (collections of article previews)
   const BlogPageLayout = require("../core/BlogPageLayout.js");
   const perPage = 10;
   for (let page = 0; page < Math.ceil(MetadataBlog.length / perPage); page++) {
@@ -258,7 +266,7 @@ function execute() {
     writeFileAndCreateFolder(targetFile, str);
   }
 
-  /* copy blog assets if they exist */
+  // copy blog assets if they exist
   if (fs.existsSync(CWD + "/blog/assets")) {
     fs.copySync(
       CWD + "/blog/assets",
@@ -266,7 +274,7 @@ function execute() {
     );
   }
 
-  /* copy all static files from docusaurus */
+  // copy all static files from docusaurus
   files = glob.sync(__dirname + "/../static/**");
   files.forEach(file => {
     let targetFile =
@@ -275,6 +283,7 @@ function execute() {
       siteConfig.projectName +
       "/" +
       file.split("/static/")[1];
+    // parse css files to replace colors according to siteConfig
     if (file.match(/\.css$/)) {
       let cssContent = fs.readFileSync(file, "utf8");
 
@@ -304,9 +313,10 @@ function execute() {
     }
   });
 
-  /* copy all static files from user */
+  // copy all static files from user
   files = glob.sync(CWD + "/static/**");
   files.forEach(file => {
+    // parse css files to replace colors according to siteConfig
     if (file.match(/\.css$/) && !isSeparateCss(file)) {
       const mainCss =
         CWD + "/build/" + siteConfig.projectName + "/css/main.css";
@@ -328,11 +338,12 @@ function execute() {
     }
   });
 
-  /* compile/copy pages from user */
+  // compile/copy pages from user
   files = glob.sync(CWD + "/pages/**");
   files.forEach(file => {
+    // render .js files to strings
     if (file.match(/\.js$/)) {
-      /* make temp file for sake of require paths */
+      // make temp file for sake of require paths
       const parts = file.split("pages");
       let tempFile = __dirname + "/../pages" + parts[1];
       tempFile = tempFile.replace(
@@ -352,10 +363,10 @@ function execute() {
       const match = regexLang.exec(file);
       const langParts = match[1].split("/");
       if (langParts.indexOf("en") !== -1) {
-        /* copy and compile a page for each enabled language from the English file */
+        // copy and compile a page for each enabled language from the English file
         for (let i = 0; i < enabledLanguages.length; i++) {
           let language = enabledLanguages[i];
-          /* skip conversion from english file if a file exists for this language */
+          // skip conversion from english file if a file exists for this language 
           if (
             language !== "en" &&
             fs.existsSync(file.replace("/en/", "/" + language + "/"))
@@ -374,7 +385,7 @@ function execute() {
           );
         }
       } else {
-        /* allow for rendering of other files not in pages/en folder */
+        // allow for rendering of other files not in pages/en folder
         let language = "en";
         for (let i = 0; i < langParts.length; i++) {
           if (enabledLanguages.indexOf(langParts[i]) !== -1) {
@@ -392,6 +403,7 @@ function execute() {
 
       fs.removeSync(tempFile);
     } else if (!fs.lstatSync(file).isDirectory()) {
+      // copy other non .js files
       let parts = file.split("pages");
       let targetFile =
         CWD + "/build/" + siteConfig.projectName + "/" + parts[1];
@@ -400,7 +412,7 @@ function execute() {
     }
   });
 
-  /* copy html files in 'en' to base level as well */
+  // copy html files in 'en' to base level as well
   files = glob.sync(CWD + "/build/" + siteConfig.projectName + "/en/**");
   files.forEach(file => {
     let targetFile = file.replace("en/", "");
@@ -409,7 +421,7 @@ function execute() {
     }
   });
 
-  /* Generate CNAME file if a custom domain is specified in siteConfig */
+  // Generate CNAME file if a custom domain is specified in siteConfig
   if (siteConfig.cname) {
     let targetFile = CWD + "/build/" + siteConfig.projectName + "/CNAME";
     fs.writeFileSync(targetFile, siteConfig.cname);
diff --git a/lib/server/readCategories.js b/lib/server/readCategories.js
index d72d238a5d..80a77de245 100644
--- a/lib/server/readCategories.js
+++ b/lib/server/readCategories.js
@@ -23,6 +23,8 @@ if (fs.existsSync(CWD + "/languages.js")) {
     }
   ];
 }
+
+// returns data broken up into categories for a sidebar
 function readCategories(sidebar) {
   const enabledLanguages = [];
   languages.filter(lang => lang.enabled).map(lang => {
diff --git a/lib/server/readMetadata.js b/lib/server/readMetadata.js
index 3ff3f6e860..10a7a9739e 100644
--- a/lib/server/readMetadata.js
+++ b/lib/server/readMetadata.js
@@ -30,6 +30,7 @@ if (fs.existsSync(CWD + "/languages.js")) {
   ];
 }
 
+// returns map from id to object containing sidebar ordering info
 function readSidebar() {
   let allSidebars;
   if (fs.existsSync(CWD + "/sidebars.json")) {
@@ -69,6 +70,7 @@ function readSidebar() {
   return order;
 }
 
+// split markdown header
 function splitHeader(content) {
   const lines = content.split("\n");
   let i = 1;
@@ -173,6 +175,7 @@ function processMetadata(file) {
   return { metadata, rawContent: rawContent };
 }
 
+// process metadata for all docs and save into core/metadata.js
 function generateDocsMetadata() {
   const order = readSidebar();
 
@@ -185,7 +188,7 @@ function generateDocsMetadata() {
 
   const metadatas = {};
 
-  /* metadata for english files */
+  // metadata for english files
   let files = glob.sync(CWD + "/../docs/**");
   files.forEach(file => {
     let language = "en";
@@ -202,7 +205,7 @@ function generateDocsMetadata() {
     }
   });
 
-  /* metadata for non-english docs */
+  // metadata for non-english docs
   files = glob.sync(CWD + "/translated_docs/**");
   files.forEach(file => {
     let language = "en";
@@ -227,6 +230,7 @@ function generateDocsMetadata() {
     }
   });
 
+  // metadata for versioned docs
   const versionData = versionFallback.docData();
   versionData.forEach(metadata => {
     const id = metadata.localized_id;
@@ -262,6 +266,7 @@ function generateDocsMetadata() {
   );
 }
 
+// process metadata for blog posts and save into core/MetadataBlog.js
 function generateBlogMetadata() {
   const metadatas = [];
 
diff --git a/lib/server/server.js b/lib/server/server.js
index dec74641bd..bba4e12ca2 100644
--- a/lib/server/server.js
+++ b/lib/server/server.js
@@ -101,7 +101,7 @@ function execute(port) {
 
   reloadMetadata();
 
-  /* handle all requests for document pages */
+  // handle all requests for document pages
   const app = express().get(/docs\/.*html$/, (req, res, next) => {
     removeFromCache(CWD + "/siteConfig.js");
     siteConfig = require(CWD + "/siteConfig.js");
@@ -110,13 +110,15 @@ function execute(port) {
 
     reloadMetadata();
 
-    // links is a map from a permalink to an id
+    // links is a map from a permalink to an id for each document
     let links = {};
     Object.keys(Metadata).forEach(id => {
       const metadata = Metadata[id];
       links[metadata.permalink] = id;
     });
-
+    
+    // mdToHtml is a map from a markdown file name to its html link, used to
+    // change relative markdown links that work on GitHub into actual site links
     const mdToHtml = {};
     Object.keys(Metadata).forEach(id => {
       const metadata = Metadata[id];
@@ -140,6 +142,7 @@ function execute(port) {
     }
     const language = metadata.language;
 
+    // determine what file to use according to its id
     let file;
     if (metadata.original_id) {
       if (ENABLE_TRANSLATION && metadata.language !== "en") {
@@ -165,7 +168,7 @@ function execute(port) {
     let rawContent = readMetadata.extractMetadata(fs.readFileSync(file, "utf8"))
       .rawContent;
 
-    /* generate table of contents if appropriate */
+    // generate table of contents if appropriate
     if (rawContent && rawContent.indexOf(TABLE_OF_CONTENTS_TOKEN) !== -1) {
       rawContent = insertTableOfContents(rawContent);
     }
@@ -177,7 +180,7 @@ function execute(port) {
       )[0];
     }
 
-    /* replace any links to markdown files to their website html links */
+    // replace any links to markdown files to their website html links
     Object.keys(mdToHtml).forEach(function(key, index) {
       let link = mdToHtml[key];
       link = link.replace("/en/", "/" + language + "/");
@@ -193,6 +196,7 @@ function execute(port) {
       );
     });
 
+    // replace any relative links to static assets to absolute links
     rawContent = rawContent.replace(
       /\]\(assets\//g,
       "](" + siteConfig.baseUrl + "docs/assets/"
@@ -209,7 +213,7 @@ function execute(port) {
     res.send(renderToStaticMarkup(docComp));
   });
 
-  /* handle all requests for blog pages and posts */
+  // handle all requests for blog pages and posts
   app.get(/blog\/.*html$/, (req, res) => {
     removeFromCache(CWD + "/siteConfig.js");
     siteConfig = require(CWD + "/siteConfig.js");
@@ -220,11 +224,11 @@ function execute(port) {
     readMetadata.generateBlogMetadata();
     const MetadataBlog = require("../core/MetadataBlog.js");
 
-    /* generate all of the blog pages */
+    // generate all of the blog pages
     removeFromCache("../core/BlogPageLayout.js");
     const BlogPageLayout = require("../core/BlogPageLayout.js");
     const blogPages = {};
-    /* make blog pages with 10 posts per page */
+    // make blog pages with 10 posts per page
     const perPage = 10;
     for (
       let page = 0;
@@ -296,12 +300,12 @@ function execute(port) {
     }
   });
 
-  /* handle all other main pages */
+  // handle all other main pages
   app.get("*.html", (req, res, next) => {
     removeFromCache(CWD + "/siteConfig.js");
     siteConfig = require(CWD + "/siteConfig.js");
 
-    /* look for user provided html file first */
+    // look for user provided html file first
     let htmlFile = req.path.toString().replace(siteConfig.baseUrl, "");
     htmlFile = CWD + "/pages/" + htmlFile;
     if (
@@ -317,7 +321,7 @@ function execute(port) {
       return;
     }
 
-    /* look for user provided react file either in specified path or in path for english files */
+    // look for user provided react file either in specified path or in path for english files
     let file = req.path.toString().replace(/\.html$/, ".js");
     file = file.replace(siteConfig.baseUrl, "");
     let userFile = CWD + "/pages/" + file;
@@ -340,8 +344,8 @@ function execute(port) {
       englishFile = englishFile.replace("/" + language + "/", "/en/");
     }
 
-    /* check for: a file for the page, an english file for page with unspecified language, 
-       english file for the page */
+    // check for: a file for the page, an english file for page with unspecified language, 
+    // english file for the page
     if (
       fs.existsSync(userFile) ||
       fs.existsSync(
@@ -352,7 +356,7 @@ function execute(port) {
       ) ||
       fs.existsSync((userFile = englishFile))
     ) {
-      /* copy into docusaurus so require paths work */
+      // copy into docusaurus so require paths work
       let parts = userFile.split("pages/");
       let tempFile = __dirname + "/../pages/" + parts[1];
       tempFile = tempFile.replace(
@@ -362,7 +366,7 @@ function execute(port) {
       mkdirp.sync(tempFile.replace(new RegExp("/[^/]*$"), ""));
       fs.copySync(userFile, tempFile);
 
-      /* render into a string */
+      // render into a string
       removeFromCache(tempFile);
       const ReactComp = require(tempFile);
       removeFromCache("../core/Site.js");
@@ -383,7 +387,7 @@ function execute(port) {
     }
   });
 
-  /* generate the main.css file by concatenating user provided css to the end */
+  // generate the main.css file by concatenating user provided css to the end
   app.get(/main\.css$/, (req, res) => {
     const mainCssPath =
       __dirname +
@@ -422,6 +426,7 @@ function execute(port) {
     res.send(cssContent);
   });
 
+  // serve static assets from these locations
   app.use(
     siteConfig.baseUrl + "docs/assets/",
     express.static(CWD + "/../docs/assets")
@@ -433,6 +438,8 @@ function execute(port) {
   app.use(siteConfig.baseUrl, express.static(CWD + "/static"));
   app.use(siteConfig.baseUrl, express.static(__dirname + "/../static"));
 
+  // "redirect" requests to pages ending with "/" or no extension so that
+  // request to "...blog" returns same result as "...blog/index.html"
   app.get(/\/[^\.]*\/?$/, (req, res) => {
     if (req.path.toString().endsWith("/")) {
       request.get(
diff --git a/lib/server/translation.js b/lib/server/translation.js
index 1ce2057eb1..503bef101a 100644
--- a/lib/server/translation.js
+++ b/lib/server/translation.js
@@ -1,3 +1,14 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+// translation object contains all translations for each string in 18n/en.json
+
 const CWD = process.cwd();
 const fs = require("fs");
 const glob = require("glob");
diff --git a/lib/start-server.js b/lib/start-server.js
index 49163d46e0..4f09dc061b 100755
--- a/lib/start-server.js
+++ b/lib/start-server.js
@@ -34,5 +34,6 @@ program.option("--port <number>", "Specify port number").parse(process.argv);
 
 const port = program.port || 3000;
 
+// start local server on specified port
 const server = require("./server/server.js");
 server(port);
diff --git a/lib/write-translations.js b/lib/write-translations.js
index fcfd6697dc..869c1e95d7 100755
--- a/lib/write-translations.js
+++ b/lib/write-translations.js
@@ -37,7 +37,7 @@ function execute() {
     "pages-strings": {}
   };
 
-  /* look through front matter of docs for titles and categories to translate */
+  // look through markdown headers of docs for titles and categories to translate
   let files = glob.sync(CWD + "/../docs/**");
   files.forEach(file => {
     const extension = path.extname(file);
@@ -56,14 +56,14 @@ function execute() {
       }
     }
   });
-  /* look through header links for text to translate */
+  // look through header links for text to translate
   siteConfig.headerLinks.forEach(link => {
     if (link.label) {
       translations["localized-strings"][link.label] = link.label;
     }
   });
 
-  /* find sidebar category titles to translate */
+  // find sidebar category titles to translate 
   Object.keys(sidebars).forEach(sb => {
     const categories = sidebars[sb];
     Object.keys(categories).forEach(category => {
@@ -85,7 +85,7 @@ function execute() {
     });
   });
 
-  /* go through pages to look for text inside translate tags */
+  // go through pages to look for text inside translate tags
   files = glob.sync(CWD + "/pages/en/**");
   files.forEach(file => {
     const extension = path.extname(file);