Update JSDoc

[zghera]

Issue summary

Update JSDoc to follow the standards outlined in the Google JS StyleGuide and the JSDoc documentation (cheat-sheet too).

Expected behavior

Good looking JSDoc when generated with jsdoc path/to/file.js. Also add a script in package.json (such as the one here) as well as a conf.json file like the one here.

Actual behavior

Current correct JSDoc usage is flaky.

[zghera]

@ananyeet 's initial comment in chat for reference:

if you're making a type (i.e. trip, activity), make a typedef:

/**
 * An activity object. 
 * @typedef {Object} ActivityInfo
 * @property {string} id The activity's ID in the database.
 * @property {string} tripId The activity's tripId in the database.
 * @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} [description] The activity's description.
 */

1D arrays marked as string[] and 2D marked as Array.<string[]> but this could be optional, just nice to read. Like I have an array that's marked as {Array.<string, ActivityInfo[]>}

btw code with the single ticks ` doesn't work, use and

code on a new line uses

 and 

props look really nice like this:

/**
 * React component for a single day of activities. 
 * 
 * @property {Object} props ReactJS props. 
 * @property {ActivityInfo[]} props.activities The list of activities for 'today'.
 * @property {string} props.date The date, formatted as 'MM/DD/YYYY'.
 */

and the real tag is @return not @returns

oh yeah and https://devhints.io/jsdoc this site is nice

[zghera]

Found another thing here, the @override annotation is preferred over @inheritdoc. Especially so when you are including other documentation in the same JSDoc comment like here: