Merge pull request #101 from googleinterns/activity-jsdocs

JSDocs for activity files

.gitignore

@@ -10,3 +10,4 @@ target/
 
 # Don't include log files
 *.log
+frontend/docs/*

frontend/src/components/Utils/time.js

@@ -6,7 +6,7 @@ import { firestore } from 'firebase';
  * Format a timestamp (in milliseconds) into a pretty string with just the time.
  * Example: '10:19 AM'.
  *
- * @param {int} msTimestamp Timestamp in milliseconds of desired date.
+ * @param {number} msTimestamp Timestamp in milliseconds of desired date.
  * @param {?string} [timezone=null] Timezone in which to convert.
  * @return {string} Formatted time.
  */
@@ -23,7 +23,7 @@ export function timestampToTimeFormatted(msTimestamp, timezone =  null) {
  * Format a timestamp (in milliseconds) into a pretty string with just the date.
  * Example: 'Monday, January 19, 1970'.
  *
- * @param {int} msTimestamp Timestamp in milliseconds of desired date.
+ * @param {number} msTimestamp Timestamp in milliseconds of desired date.
  * @param {?string} [timezone=null] Timezone in which to convert.
  * @return {string} Formatted time.
  */
@@ -41,21 +41,23 @@ export function timestampToDateFormatted(msTimestamp, timezone=null) {
  * not including the day of the week..
  * Example: 'January 19, 1970'.
  *
- * @param {!number} msTimestamp Timestamp in milliseconds of desired date.
- * @param {string} [timezone='America/New_York'] Timezone in which to convert.
+ * @param {number} msTimestamp Timestamp in milliseconds of desired date.
+ * @param {?string} [timezone=null] Timezone in which to convert.
  * @return {string} Formatted time.
  */
-export function timestampToLongDate(msTimestamp, timezone='America/New_York') {
+export function timestampToLongDate(msTimestamp, timezone=null) {
   // Formats from https://momentjs.com/docs/#/displaying/format/.
   // LL = "January 19, 1970"
+  timezone = timezone != null ? timezone.replace(' ', '_') // Reformat date.
+                              : ''; // Use GMT.
   return moment.tz(parseFloat(msTimestamp), timezone).format('LL');
 }
 
 /** 
  * Format a timestamp (in milliseconds) into a pretty string.
  * Example: 'Monday, January 19, 1970 02:48 AM PST'.
  *
- * @param {int} msTimestamp Timestamp in milliseconds of desired date.
+ * @param {number} msTimestamp Timestamp in milliseconds of desired date.
  * @param {?string} [timezone=null] Timezone in which to convert.
  * @returns {string} Formatted time.
  */
@@ -128,9 +130,10 @@ export function timestampToISOString(timestamp) {
 
 /**
  * Returns all the time zones in a country (in displayable format).
- *
- * @param {string} countryName The name of the country for which to get the time zones.
+ * 
+ * @param {?string} countryName The name of the country for which to get the time zones.
  * @return {string[]} The list of time zones in the provided country.
+ *  Null or unfamiliar values of `countryName` will return the list of all timezones.
  */
 export function timezonesForCountry(countryName) {
   let zones;
@@ -151,6 +154,7 @@ export function timezonesForCountry(countryName) {
  * @param {number} msTimestamp Timestamp, in milliseconds since epoch.
  * @param {?string} [timezone=null] The timezone which the string should be returned in.
  * @return {string} The date in 'YYYY-MM-DD' format. 
+ *  A null value will return timezone in GMT.
  */
 export function getISODate(msTimestamp, timezone=null) {
   timezone = timezone != null ? timezone.replace(' ', '_') // Reformat date.
@@ -164,6 +168,7 @@ export function getISODate(msTimestamp, timezone=null) {
  * @param {number} msTimestamp Timestamp, in milliseconds since epoch.
  * @param {?string} [timezone=null] The timezone which the string should be returned in.
  * @return {string} The time in 24-hour (HH:mm) format.   
+ *  A null value will return timezone in GMT.
  */
 export function get24hTime(msTimestamp, timezone=null) {
   if (timezone === null) {

frontend/src/components/ViewActivities/activity.js

@@ -20,33 +20,26 @@ class Activity extends React.Component {
     super(props);
 
     this.state = { editing: false };
-
-    // Bind state users/modifiers to `this`.
-    this.setEditActivity = this.setEditActivity.bind(this);
-    this.finishEditActivity = this.finishEditActivity.bind(this);
-    this.displayCard = this.displayCard.bind(this);
   }
 
   /**
    * Set the activity into editing mode.
    */
-  setEditActivity() {
+  setEditActivity = () => {
     this.setState({editing: true});
   }
 
   /**
    * Set the activity into viewing mode.
-   * 
-   * @param {event} event The form's event.
    */
-  finishEditActivity(event) {
-    this.setState({editing: false});
-  };
+  finishEditActivity = () => { this.setState({editing: false}); };
 
   /**
-   * Display the current activity, either in view or display mode.
+   * Display the current activity, either in view or edit mode.
+   * 
+   * @return {JSX.Element} The current activity in correct mode.
    */
-  displayCard() {
+  displayCard = () => {
     let activity = this.props.activity;
     if (!this.state.editing) { // View mode.
       return (
@@ -81,8 +74,10 @@ class Activity extends React.Component {
             <h5>{activity[DB.ACTIVITIES_TITLE]}</h5>
             <p>{utils.displayTimes(activity)}</p>
           </Accordion.Toggle>
-          <Accordion.Collapse eventKey='0'
-            className={'view-activity' + (this.state.editing? ' edit': '')}>
+          <Accordion.Collapse 
+            eventKey='0' 
+            className={'view-activity' + (this.state.editing? ' edit': '')}
+            >
             { this.displayCard() }
           </Accordion.Collapse>
         </Card>

frontend/src/components/ViewActivities/activityfns.js

@@ -14,28 +14,31 @@ const db = app.firestore();
  * @property {string} title The activity's title.
  * @property {long} start_time Number of seconds since epoch of activity's start time.
  * @property {long} end_time Number of seconds since epoch of activity's end time.
+ * @property {string} start_tz The timezone in which the activity starts.
+ * @property {string} end_tz The timezone in which the activity ends.
+ * @property {string} [start_country] The country in which the activity starts.
+ * @property {string} [end_country] The country in which the activity ends.
  * @property {string} [description] The activity's description.
  */
 
 /**
  * A single activity day. A single instance looks like:
- * <pre><code> ['MM/DD/YYYY', [activities on that day]]</code></pre>
+ * ```['MM/DD/YYYY', [activities on that day]]```
  * @typedef {Array.<string, ActivityInfo[]>} DayOfActivities
- * 
  */
 
-/* 
+/**
  * Get the field of field name `fieldName` from `activity`  or the default value.
  * 
- * @param {Object} activity Activity to get field from.
+ * @param {ActivityInfo} activity Activity to get field from.
  * @param {string} fieldName Name of the field in the activity to get. 
- * @param {?*} [defaultValue=null] Default value to return if activity[fieldName] can't be found. 
- * Can be any type.
- * @param {string} [prefix=''] The prefix to put before a returned value if the field exists.
+ * @param {?*} [defaultValue=null] Default value to return if activity[fieldName] 
+ *  can't be found. Can be any type.
+ * @param {string} [prefix=''] The prefix to put before a returned value if the 
+ *  field exists.
  * @return {*} `activity[fieldName]` if possible, else `defaultValue`. Can be any type.
  */
-export function getField(
-    activity, fieldName, defaultValue = null, prefix = '') {
+export function getField (activity, fieldName, defaultValue = null, prefix = '') {
   if (activity[fieldName] === null || activity[fieldName] === undefined) {
     return defaultValue;
   }
@@ -45,8 +48,7 @@ export function getField(
 /**
  * Sort a list of trip activities by date. 
  * @param {ActivityInfo[]} tripActivities Array of activities.
- * @return {DayOfActivities[]} List of trip activities in the form
- * <pre><code>[ , ...]</code></pre>
+ * @return {DayOfActivities[]} List of {@link DayOfActivities}
  * in chronological order by date.
  */
 export function sortByDate(tripActivities) {
@@ -73,11 +75,11 @@ export function sortByDate(tripActivities) {
 }
 
 /**
- * Put<code>a</code> and<code>b</code> in display order. 
+ * Put`a and `b` in display order. 
  * This function is a comparator.
- * @param {ActivityInfo} a Dictionary representing activity a and its fields. 
- * @param {ActivityInfo} b Dictionary representing activity b and its fields.
- * @return {int} <code>-1</code> if <code>a</code> comes before <code>b</code>, else <code>1</code>. 
+ * @param {ActivityInfo} a Dictionary representing activity `a` and its fields. 
+ * @param {ActivityInfo} b Dictionary representing activity `b` and its fields.
+ * @return {int} `-1` if `a` comes before `b`, else `1`. 
  */
 export function compareActivities(a, b) {
   if (a[DB.ACTIVITIES_START_TIME] < b[DB.ACTIVITIES_START_TIME]) {
@@ -95,8 +97,9 @@ export function compareActivities(a, b) {
  * 
  * @param {string} tripId Database ID of the trip whose actiivty should be modified.
  * @param {string} activityId Database ID of the activity to be modified.
- * @param {Object} newValues Dictionary of the new values in <code>{fieldName: newValue}</code> form
- * @return {boolean} <code>true</code> if the write was successful, <code>false</code> otherwise. 
+ * @param {Object} newValues Dictionary of the new values in `{fieldName: newValue}`
+ *  form. None of the entries can be lists. 
+ * @return {boolean} `true` if the write was successful, `false` otherwise. 
  */
 export async function writeActivity(tripId, activityId, newValues) {
   // todo: check if tripId or activityId is not valid. (#58)
@@ -121,9 +124,11 @@ export async function writeActivity(tripId, activityId, newValues) {
 /**
  * Get the value of a reference. 
  * 
- * @param {Reference} ref Reference to get the value of.
- * @param {string} ignoreValue The "null" or "none" value that ref could be.
- * @param {string} defaultValue Value to return if ref.current.value === ignoreValue.
+ * Note: This function breaks if `ref.current` is null. This is intentional.
+ * 
+ * @param {!React.RefObject} ref Reference to get the value of.
+ * @param {?string} ignoreValue The "null" or "none" value that ref could be.
+ * @param {?string} [defaultValue=null] Value to return if ref.current.value === ignoreValue.
  * @return defaultValue if ref.current.value === ignoreValue, else ref.current.value.
  */
 export function getRefValue(ref, ignoreValue='', defaultValue=null) {

frontend/src/components/ViewActivities/activitylist.js

@@ -11,7 +11,7 @@ const db = app.firestore();
  * ReactJS class component for the list of activities. 
  * 
  * @property {Object} props ReactJS props.
- * @property {string} tripId The tripID.
+ * @property {string} props.tripId The tripID.
  */
 class ActivityList extends React.Component {
   /** @override */

frontend/src/components/ViewActivities/editActivity.js

@@ -102,7 +102,11 @@ class EditActivity extends React.Component {
     writeActivity(this.props.activity.tripId, this.props.activity.id, newVals);
   }
 
-  /** Runs when the `submit` button on the form is pressed.  */
+  /** 
+   * Runs when the `submit` button on the form is pressed. 
+   * 
+   * @param event The form event.
+   */
   finishEditActivity(event) {
     event.preventDefault();
     this.editActivity();
@@ -127,16 +131,15 @@ class EditActivity extends React.Component {
    * Returns a dropdown of all the timezones.
    * The dropdown's values change based on the corrresponding country dropdown to
    * reduce scrolling and ensure that the location corresponds to the time zone.
-   *
-   * Tests done manually using UI.
-   *
-   * @param {string} st Either 'start' or 'end' depending on whether the
+   * 
+   * @param {string} st Either 'start' or 'end' depending on whether the 
    * timezone is for the start or end timezone.
-   * @return {HTML} HTML dropdown item.
+   * @param {string} defaultTz The default time zone.
+   * @return {JSX.Element} HTML dropdown item.
    */
   timezoneDropdown(st, defaultTz) {
-    const ref = st === 'start' ? this.editStartLocRef : this.editEndLocRef;
-    const dbEntry = st === 'start' ? DB.ACTIVITIES_START_COUNTRY : DB.ACTIVITIES_END_COUNTRY;
+    let ref = st === 'start' ? this.editStartLocRef : this.editEndLocRef;
+    let dbEntry = st === 'start' ? DB.ACTIVITIES_START_COUNTRY : DB.ACTIVITIES_END_COUNTRY;
     let timezones;
     if (ref.current == null) {
       // If activity[key] DNE, then timezones will just return all tzs anyway.
@@ -164,10 +167,10 @@ class EditActivity extends React.Component {
    * so when the country changes here, the values in the timezone dropdown
    * change as well.
    *
-   * @param {ref} ref The reference to attach to the dropdown.
-   * @param {ref} onChange The function to call onChange. 
+   * @param {React.RefObject} ref The reference to attach to the dropdown.
+   * @param {function} onChange The function to call onChange. 
    * @param {string} defaultCountry The default country for the dropdown.
-   * @return {HTML} HTML dropdown of all the countries with timezones.
+   * @return {JSX.Element} HTML dropdown of all the countries with timezones.
    */
   countriesDropdown(ref, onChange, defaultCountry) {
     return (
@@ -251,7 +254,7 @@ class EditActivity extends React.Component {
           this.state.endTimeFiller, //timeDefault, 
           this.timezoneDropdown('end', getField(activity, DB.ACTIVITIES_END_TZ)), // tzpicker 
           null, // onChangeDate
-          this.state.startTimeDateChanged // key
+          this.state.startTimeDateChanged, // key
           this.state.flightCheck //show
           )}
         {formElements.textElementFormGroup( // DESCRIPTION

frontend/src/components/ViewActivities/editActivityFormElements.js

@@ -8,13 +8,13 @@ const COUNTRYWIDTH = 8;
 const TZPICKERWIDTH = 3;
 
 /**
- * Create a Text element Form Group for the editActivity form.
- *
+ * Create a Text element Form Group for the editActivity form. 
+ * 
  * @param {string} controlId FormGroup's control ID.
- * @param {string} formLabel The label of the field for this FormGroup.
- * @param {string} placeHolder The input's placeholder.
- * @param {ref} ref The input's reference.
- * @returns {HTML} A text element form group.
+ * @param {string} formLabel The label of the field for this FormGroup. 
+ * @param {string} placeHolder The input's placeholder. 
+ * @param {?React.RefObject} ref The input's reference.
+ * @return {JSX.Element} A text element form group.
  */
 export function textElementFormGroup(controlId, formLabel, placeHolder, ref) {
   return (
@@ -30,12 +30,12 @@ export function textElementFormGroup(controlId, formLabel, placeHolder, ref) {
 }
 
 /**
- * Create a Location Dropdown element Form Group for the editActivity form.
- *
+ * Create a Location Dropdown element Form Group for the editActivity form. 
+ * 
  * @param {string} controlId FormGroup's control ID.
- * @param {string} formLabel The label of the field for this FormGroup.
- * @param {string} dropdown The dropdown.
- * @returns {HTML} a location dropdown form group.
+ * @param {string} formLabel The label of the field for this FormGroup. 
+ * @param {string} dropdown The dropdown. 
+ * @return {JSX.Element} A location dropdown form group.
  */
 export function locationElementFormGroup(controlId, formLabel, dropdown, show=true) {
   if (!show) { return (<div></div>); }
@@ -50,18 +50,19 @@ export function locationElementFormGroup(controlId, formLabel, dropdown, show=tr
 /**
  * Create a Form Group for inserting date, time, and timezone for
  * the editActivity form..
- *
- * @param {string} controlId FormGroup's control ID.
- * @param {string} formLabel Label of the field for this FormGroup.
- * @param {ref} dateRef Date's reference.
- * @param {string} dateDefault Default date.
- * @param {ref} timeRef Time's reference.
- * @param {ref} timeDefault Default time.
- * @param {HTML} tzpicker Timezone picker dropdown.
- * @returns {HTML} A FormGroup for date, time, and timezone.
+ * 
+ * @param {string} controlId FormGroup's control ID. 
+ * @param {string} formLabel Label of the field for this FormGroup. 
+ * @param {?React.RefObject} dateRef Date's reference. 
+ * @param {string} dateDefault Default date. 
+ * @param {?React.RefObject} timeRef Time's reference. 
+ * @param {React.RefObject} timeDefault Default time. 
+ * @param {JSX.Element} tzpicker Timezone picker dropdown. 
+ * @return {JSX.Element} A FormGroup for date, time, and timezone.  
  */
 export function dateTimeTzFormGroup(controlId, formLabel, dateRef,
   dateDefault, timeRef, timeDefault, tzpicker, onChangeDate=null, key=null, show=true) {
+  if (!show) {return (<div></div>); }
   return (
   <Form.Group as={Row} controlId={controlId} key={key}>
       <Col sm={TITLEWIDTH}><Form.Label>{formLabel}</Form.Label></Col>
@@ -91,7 +92,7 @@ export function dateTimeTzFormGroup(controlId, formLabel, dateRef,
  * @param {React.RefObject} ref The input's reference.
  * @param {function} onChange The function to call onChange.
  * @param {boolean} defaultValue The default value of the checkbox (true for checked).
- * @return {HTML} A FormGroup with the checkbox.
+ * @return {JSX.Element} A FormGroup with the checkbox.
  */
 export function flightCheck(controlId, formLabel, ref, onChange, defaultValue) {
   return (