Merge pull request #323 from mewtaylor/bugfix/readme-update

Added some more documentation

README.md

@@ -39,7 +39,7 @@ Use `^C` to stop the node process `npm start` starts.
 | `PORT`        | `8333`                                | Port for devserver (http://localhost:XXXX)     |
 | `FALLBACK`  | `''`             | Pass-through location for old site            |
 
-**NOTE:** Because by default both `API_HOST=https://api.scratch.mit.edu` and `FALLBACK=https://scratch.mit.edu`, please be aware that, by default, you will be seeing and interacting with real data on the Scratch website.
+**NOTE:** Because by default `API_HOST=https://api.scratch.mit.edu`, please be aware that, by default, you will be seeing and interacting with real data on the Scratch website.
 
 ### To Test
 ```bash
@@ -56,3 +56,5 @@ Most of the issues we have currently revolve around the use of `FALLBACK`. This
 Setting `FALLBACK=https://scratch.mit.edu` allows the web client to retrieve data from the Scratch website in your development environment. However, because of security concerns, trying to send data to Scratch through your development environment won't work. This means the following things will be broken for the time being:
 * Login on the splash page (*In the process of being fixed*)
 * Some update attempts to production data made through a development version of the web client
+
+Additionally, if you set `FALLBACK=https://scratch.mit.edu`, be aware that clicking on links to parts of the website not yet migrated over (currently such as `Explore`, `Discuss`, `Profile`, etc.) will take you to the Scratch website itself.

src/components/banner/banner.jsx

@@ -3,6 +3,10 @@ var React = require('react');
 
 require('./banner.scss');
 
+/**
+ * Container for messages displayed below the nav bar that can be dismissed
+ * (See: email not confirmed banner)
+ */
 var Banner = React.createClass({
     type: 'Banner',
     propTypes: {

src/components/carousel/carousel.jsx

@@ -9,6 +9,9 @@ require('slick-carousel/slick/slick.scss');
 require('slick-carousel/slick/slick-theme.scss');
 require('./carousel.scss');
 
+/**
+ * Displays content in horizontal scrolling box. Example usage: splash page rows.
+ */
 var Carousel = React.createClass({
     type: 'Carousel',
     propTypes: {

src/components/languagechooser/languagechooser.jsx

@@ -8,6 +8,9 @@ var Select = require('../forms/select.jsx');
 
 require('./languagechooser.scss');
 
+/**
+ * Footer dropdown menu that allows one to change their language.
+ */
 var LanguageChooser = React.createClass({
     type: 'LanguageChooser',
     mixins: [

src/components/modal/modal.jsx

@@ -25,6 +25,9 @@ var defaultStyle = {
     }
 };
 
+/**
+ * Container for pop up windows (See: registration window)
+ */
 var Modal = React.createClass({
     type: 'Modal',
     statics: {

src/components/navigation/navigation.jsx

@@ -47,14 +47,14 @@ var Navigation = React.createClass({
             loginOpen: false,
             loginError: null,
             registrationOpen: false,
-            unreadMessageCount: 0,
-            messageCountIntervalId: -1
+            unreadMessageCount: 0, // bubble number to display how many notifications someone has.
+            messageCountIntervalId: -1 // javascript method interval id for getting messsage count.
         };
     },
     componentDidMount: function () {
         if (this.state.session.user) {
             this.getMessageCount();
-            var intervalId = setInterval(this.getMessageCount, 120000);
+            var intervalId = setInterval(this.getMessageCount, 120000); // check for new messages every 2 mins.
             this.setState({'messageCountIntervalId': intervalId});
         }
     },

src/components/subnavigation/subnavigation.jsx

@@ -3,6 +3,10 @@ var React = require('react');
 
 require('./subnavigation.scss');
 
+/**
+ * Container for a custom, horizontal list of navigation elements
+ * that can be displayed within a view or component.
+ */
 var SubNavigation = React.createClass({
     type: 'SubNavigation',
     render: function () {

src/lib/intl.jsx

@@ -2,6 +2,9 @@ var ReactIntl = require('react-intl');
 
 var customLanguages = require('../../custom-locales.json');
 
+/**
+ * Add custom locales to react-intl if it doesn't have them.
+ */
 for (var locale in customLanguages) {
     ReactIntl.addLocaleData(customLanguages[locale]);
 }

src/lib/jar.js

 var cookie = require('cookie');
 var xhr = require('xhr');
 
+/**
+ * Module that handles coookie interactions.
+ *     (Cookies?!?! Jar?!?! Get it?!?! WE'RE AMAZING!!!!)
+ *
+ * get(name, callback) – can be sync or async, as callback is optional
+ * set(name, value) – synchronously sets the cookie
+ * use(name, uri, callback) – can by sync or async, gets cookie from the uri if not there.
+ */
 var Jar = {};
 
 Jar.get = function (name, callback) {

src/mixins/api.jsx

@@ -6,6 +6,14 @@ var log = require('../lib/log.js');
 
 var CookieMixinFactory = require('./cookieMixinFactory.jsx');
 
+/**
+ * Component mixin that constructs requests to the scratch api.
+ * Custom arguments:
+ *     - useCsrf [boolean] – handles unique csrf token retrieval for POST requests. This prevents
+ *       CSRF forgeries (see: https://www.squarefree.com/securitytips/web-developers.html#CSRF)
+ *
+ * It also takes in other arguments specified in the xhr library spec.
+ */
 var Api = {
     mixins: [
         // Provides useScratchcsrftoken

src/views/splash/splash.jsx

@@ -28,11 +28,11 @@ var Splash = injectIntl(React.createClass({
     getInitialState: function () {
         return {
             projectCount: 10569070,
-            activity: [],
-            news: [],
-            featuredCustom: {},
-            featuredGlobal: {},
-            showEmailConfirmationModal: false,
+            activity: [], // recent social actions taken by users someone is following
+            news: [], // gets news posts from the scratch Tumblr
+            featuredCustom: {}, // custom homepage rows, such as "Projects by Scratchers I'm Following"
+            featuredGlobal: {}, // global homepage rows, such as "Featured Projects"
+            showEmailConfirmationModal: false, // flag that determines whether to show banner to request email conf.
             refreshCacheStatus: 'notrequested'
         };
     },