finish adding comments where needed

vivshaw · Aug 28, 2017 · 2fb6035 · 2fb6035
1 parent 9147138
commit 2fb6035
Show file tree

Hide file tree

Showing 8 changed files with 80 additions and 23 deletions.
diff --git a/docs/documentation.yml b/docs/documentation.yml
@@ -41,7 +41,23 @@ toc:
   - TopBar
 
   - name: common/flowTypes
-  - flowTypes
+  - BookType
 
   - name: common/searchTerms
   - searchTerms
+
+  - name: utils/BooksAPI
+  - get
+  - getAll
+  - update
+  - search
+  - defaultToHTTPS
+
+  - name: utils/getWidth
+  - getWidth
+  - widths
+
+  - name: utils/RatingsAPI
+  - getAllRatings
+  - getRating
+  - setRating
diff --git a/public/index.html b/public/index.html
@@ -8,19 +8,22 @@
       <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, shrink-to-fit=no">
     -->
 
-    <link rel="manifest" href="%PUBLIC_URL%/manifest.json">
-    <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">
+    <!-- Progressive web app stuff & favicons -->
     <link rel="apple-touch-icon" sizes="180x180" href="%PUBLIC_URL%/apple-touch-icon.png">
-    <link rel="icon" type="image/png" href="%PUBLIC_URL%/favicon-32x32.png" sizes="32x32">
     <link rel="icon" type="image/png" href="%PUBLIC_URL%/favicon-16x16.png" sizes="16x16">
+    <link rel="icon" type="image/png" href="%PUBLIC_URL%/favicon-32x32.png" sizes="32x32">
+    <link rel="manifest" href="%PUBLIC_URL%/manifest.json">
     <link rel="mask-icon" href="%PUBLIC_URL%/safari-pinned-tab.svg" color="#5bbad5">
+    <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">
     <meta name="theme-color" content="#ffab91">
 
+    <!-- verification for Google web tools -->
     <meta name="google-site-verification" content="fewu-p7BADBGC62LAsUZ0rBVUoaxBt1ym0t0zLJ7Ozs" />
 
+    <!-- pull in Google Material Icons for our FontIcons -->
     <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
 
-    <title>flybrary</title>
+    <title>Flybrary</title>
   </head>
   <body>
     <noscript>

diff --git a/public/manifest.json b/public/manifest.json
@@ -1,6 +1,6 @@
 {
-	"short_name": "Flybrary",
-	"name": "Flybrary",
+	"background_color": "#ffab91",
+	"display": "standalone",
 	"icons": [
 		{
 			"src": "/android-chrome-192x192.png",
@@ -13,10 +13,10 @@
 			"type": "image/png"
 		}
 	],
-	"start_url": "/",
+	"name": "Flybrary",
+	"orientation": "portrait",
 	"scope": "/",
-	"theme_color": "#ffab91",
-	"background_color": "#ffab91",
-	"display": "standalone",
-	"orientation": "portrait"
+	"short_name": "Flybrary",
+	"start_url": "/",
+	"theme_color": "#ffab91"
 }
diff --git a/src/common/flowTypes.js b/src/common/flowTypes.js
@@ -4,6 +4,7 @@
 
 /**
  * Book object type, returned as JSOn from the BooksAPI
+ * @name BookType
  * @type {BookType}
  * @prop {Array<string>} authors				the book's authors
  * @prop {string} description						a short description of the book

diff --git a/src/index.js b/src/index.js
@@ -1,20 +1,28 @@
+// Vendor
 import React from 'react';
+import { BrowserRouter } from 'react-router-dom';
 import { render } from 'react-snapshot';
 import injectTapEventPlugin from 'react-tap-event-plugin';
-import { BrowserRouter } from 'react-router-dom';
-import './index.css';
-import App from './components/App';
 import registerServiceWorker from './registerServiceWorker';
-import 'typeface-roboto';
+
+// Components
+import App from './components/App';
+
+// Styles
 import 'sanitize.css';
+import './index.css';
+import 'typeface-roboto';
 
+// needed so tap events work in Material-UI
 injectTapEventPlugin();
 
+// React is go!
 render(
 	<BrowserRouter>
 		<App />
 	</BrowserRouter>,
 	document.getElementById('root')
 );
 
+// Activate CRA's service worker for offline app use
 registerServiceWorker();
diff --git a/src/setupTests.js b/src/setupTests.js
@@ -1,3 +1,5 @@
+/* Set up mock for localStorage so that our tests will run */
+
 const localStorageMock = {
 	getItem: jest.fn(),
 	setItem: jest.fn(),

diff --git a/src/utils/BooksAPI.js b/src/utils/BooksAPI.js
@@ -6,7 +6,11 @@ import type { BookType } from '../common/flowTypes';
 /* 	Modified versions of provided helper methods from Udacity BooksAPI. I've
 		tweaked them a bit and added Flow to them */
 
-/** Books API endpoint */
+/* ------------------------------------------------------------------
+   ----------------------------- SETUP ------------------------------
+	 ------------------------------------------------------------------ */
+
+/* Books API endpoint */
 const api = 'https://reactnd-books-api.udacity.com';
 
 /* Access token for books API */
@@ -24,19 +28,23 @@ try {
 	token = Math.random().toString(36).substr(-8);
 }
 
+/* JSON headers for books API */
+const headers = {
+	Accept: 'application/json',
+	Authorization: token
+};
+
+/* ------------------------------------------------------------------
+   ------------------------- API METHODS ----------------------------
+	 ------------------------------------------------------------------ */
+
 /**
  * Translates an insecure http  url to a secure https one.
  * @param  {string} url insecure url
  * @return {string}     https url
  */
 const defaultToHTTPS = url => 'https' + url.substring(4);
 
-/* JSON headers for books API */
-const headers = {
-	Accept: 'application/json',
-	Authorization: token
-};
-
 /**
  * Fetch one book from the API, by id.
  * @param  {string} bookId id of the book to get

diff --git a/src/utils/RatingsAPI.js b/src/utils/RatingsAPI.js
@@ -1,8 +1,17 @@
 // @flow
 
+/* localStorage API for book rating system. Since the books API has no ratings,
+   we'll just store them in localStorage & provide helpers to abstract over that. */
+
+/**
+ * Get all the ratings for all books
+ * @return {ratings} An object containing a key for each rated book with a value that is that book's rating
+ */
 export const getAllRatings = () => {
 	let ratings;
 
+	/* If ratings aren't yet initialized, do that first. If they're unsupported
+	   due to being on the server-side, make ratings an empty object. */
 	try {
 		let ratingsItem = localStorage.getItem('ratings');
 
@@ -19,6 +28,11 @@ export const getAllRatings = () => {
 	return ratings;
 };
 
+/**
+ * Get the rating for a particular book, by ID
+ * @param  {string} id the id of the book we want the rating for
+ * @return {number}    the rating of that book
+ */
 export const getRating = (id: string): number => {
 	const ratings = getAllRatings();
 
@@ -30,6 +44,11 @@ export const getRating = (id: string): number => {
 	}
 };
 
+/**
+ * Set the rating for a particular book, by id.
+ * @param {string} id     the id of the book to rate
+ * @param {number} rating the rating to assign
+ */
 export const setRating = (id: string, rating: number) => {
 	let ratings = getAllRatings();