feat(build): issues/231 code documentation, linting (#232)

* build, apply jsdoc eslint
* router, expand on missing propTypes
* i18n, snapshot update

.eslintrc

@@ -9,6 +9,7 @@
   "plugins": [
     "import",
     "jest",
+    "jsdoc",
     "json",
     "prettier",
     "react"
@@ -18,7 +19,8 @@
     "airbnb",
     "airbnb/hooks",
     "prettier",
-    "plugin:jest/recommended"
+    "plugin:jest/recommended",
+    "plugin:jsdoc/recommended"
   ],
   "rules": {
     "arrow-parens": [
@@ -46,6 +48,24 @@
     "import/no-named-as-default-member": 0,
     "jest/no-test-callback": 0,
     "jest/prefer-to-have-length": 0,
+    "jsdoc/check-tag-names": [
+      2,
+      {
+        "definedTags": [
+          "api",
+          "apiDescription",
+          "apiSuccess",
+          "apiSuccessExample",
+          "apiError",
+          "apiErrorExample",
+          "apiMock",
+          "apiParam"
+        ]
+      }
+    ],
+    "jsdoc/require-param-description": 0,
+    "jsdoc/require-property-description": 0,
+    "jsdoc/require-returns-description": 0,
     "max-len": [
       "error",
       {

package.json

@@ -121,6 +121,7 @@
     "eslint-config-prettier": "^6.10.0",
     "eslint-plugin-import": "^2.20.1",
     "eslint-plugin-jest": "^23.8.2",
+    "eslint-plugin-jsdoc": "^22.0.1",
     "eslint-plugin-json": "^2.1.1",
     "eslint-plugin-jsx-a11y": "^6.2.3",
     "eslint-plugin-prettier": "^3.1.2",

src/common/dateHelpers.js

@@ -2,9 +2,23 @@ import moment from 'moment/moment';
 import { helpers } from './helpers';
 import { RHSM_API_QUERY_GRANULARITY_TYPES as GRANULARITY_TYPES } from '../types/rhsmApiTypes';
 
+/**
+ * Return a date.
+ *
+ * @returns {string|Date}
+ */
 const getCurrentDate = () =>
   (helpers.TEST_MODE && '20190720') || (helpers.DEV_MODE && process.env.REACT_APP_DEBUG_DEFAULT_DATETIME) || new Date();
 
+/**
+ * Set a date range based on a granularity type.
+ *
+ * @param {object} params
+ * @property {Date} date Start date, typically the current date.
+ * @property {number} subtract Number of granularity type to subtract from the current date.
+ * @property {string} measurement Granularity type.
+ * @returns {{endDate: Date, startDate: Date}}
+ */
 const setRangedDateTime = ({ date, subtract, measurement }) => ({
   startDate: moment
     .utc(date)
@@ -24,7 +38,7 @@ const monthlyDateTime = setRangedDateTime({ date: getCurrentDate(), subtract: 12
 const quarterlyDateTime = setRangedDateTime({ date: getCurrentDate(), subtract: 36, measurement: 'months' });
 
 /**
- * Return a range of time based on granularity.
+ * Return a range of time based on known granularity types.
  *
  * @param {string} granularity
  * @returns {{endDate: Date, startDate: Date}}
@@ -43,20 +57,35 @@ const getRangedDateTime = granularity => {
   }
 };
 
+/**
+ * Consistent timestamp day formats.
+ *
+ * @type {{short: string, yearShort: string, yearLong: string, long: string}}
+ */
 const timestampDayFormats = {
   long: 'MMMM D',
   yearLong: 'MMMM D YYYY',
   short: 'MMM D',
   yearShort: 'MMM D YYYY'
 };
 
+/**
+ * Consistent timestamp month formats.
+ *
+ * @type {{short: string, yearShort: string, yearLong: string, long: string}}
+ */
 const timestampMonthFormats = {
   long: 'MMMM',
   yearLong: 'MMMM YYYY',
   short: 'MMM',
   yearShort: 'MMM YYYY'
 };
 
+/**
+ * Consistent timestamp quarter formats.
+ *
+ * @type {{short: string, yearShort: string, yearLong: string, long: string}}
+ */
 const timestampQuarterFormats = {
   ...timestampMonthFormats
 };

src/common/helpers.js

@@ -1,44 +1,171 @@
+/**
+ * Generate a random'ish ID.
+ *
+ * @param {string} prefix
+ * @returns {string}
+ */
 const generateId = prefix =>
   `${prefix || 'generatedid'}-${(process.env.REACT_APP_ENV !== 'test' && Math.ceil(1e5 * Math.random())) || ''}`;
 
+// ToDo: expand to include "async" check in scenarios where async/await are utilized.
+/**
+ * Check if "is a Promise".
+ *
+ * @param {Promise|*} obj
+ * @returns {boolean}
+ */
 const isPromise = obj => Object.prototype.toString.call(obj) === '[object Promise]';
 
+/**
+ * An empty function.
+ * Typically used as a default prop.
+ */
 const noop = Function.prototype;
 
+/**
+ * An empty promise.
+ * Typically used as a default prop, or during testing.
+ *
+ * @type {Promise<{}>}
+ */
 const noopPromise = Promise.resolve({});
 
+/**
+ * A placeholder for "t", translation method.
+ * Associated with the i18n package, and typically used as a default prop.
+ *
+ * @param {string} key
+ * @param {string} value
+ * @returns {string}
+ */
 const noopTranslate = (key, value) => `t(${key}${(value && `, ${value}`) || ''})`;
 
+/**
+ * Is dev mode active.
+ * Associated with using the NPM script "start". See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const DEV_MODE = process.env.REACT_APP_ENV === 'development';
 
+/**
+ * Is prod mode active.
+ * Associated with production builds. See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const PROD_MODE = process.env.REACT_APP_ENV === 'production';
 
+/**
+ * Is review/proxy mode active.
+ * Associated with using the NPM script "start:proxy". See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const REVIEW_MODE = process.env.REACT_APP_ENV === 'review';
 
+/**
+ * Is test mode active.
+ * Associated with running unit tests. See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const TEST_MODE = process.env.REACT_APP_ENV === 'test';
 
+/**
+ * Apply a path prefix for routing.
+ * Typically associated with applying a "beta" path prefix. See dotenv config files for updating. See build scripts for generated prefix.
+ *
+ * @type {string}
+ */
 const UI_DEPLOY_PATH_PREFIX = process.env.REACT_APP_UI_DEPLOY_PATH_PREFIX;
 
+/**
+ * Disable an aspect of the UI.
+ * Typically associated with disabling views through route settings. See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const UI_DISABLED = process.env.REACT_APP_UI_DISABLED === 'true';
 
+/**
+ * Disable the graph card aspect of the UI.
+ * See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const UI_DISABLED_GRAPH = process.env.REACT_APP_UI_DISABLED_GRAPH === 'true';
 
+/**
+ * Disable the inventory/table aspect of the UI.
+ * See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const UI_DISABLED_TABLE = process.env.REACT_APP_UI_DISABLED_TABLE === 'true';
 
+/**
+ * Disable the filter toolbar aspect of the UI.
+ * See dotenv config files for activation.
+ *
+ * @type {boolean}
+ */
 const UI_DISABLED_TOOLBAR = process.env.REACT_APP_UI_DISABLED_TOOLBAR === 'true';
 
+/**
+ * UI application name.
+ * See dotenv config files for updating.
+ *
+ * @type {string}
+ */
 const UI_DISPLAY_NAME = process.env.REACT_APP_UI_DISPLAY_NAME;
 
+/**
+ * UI application configuration name.
+ * See dotenv config files for updating.
+ *
+ * @type {string}
+ */
 const UI_DISPLAY_CONFIG_NAME = process.env.REACT_APP_UI_DISPLAY_CONFIG_NAME;
 
+/**
+ * UI application sentence start name.
+ * See dotenv config files for updating.
+ *
+ * @type {string}
+ */
 const UI_DISPLAY_START_NAME = process.env.REACT_APP_UI_DISPLAY_START_NAME;
 
+/**
+ * UI state logging name/id.
+ * See dotenv config files for updating.
+ *
+ * @type {string}
+ */
 const UI_LOGGER_ID = process.env.REACT_APP_UI_LOGGER_ID || 'GUI';
 
+/**
+ * UI packaged application name.
+ * See dotenv config files for updating.
+ *
+ * @type {string}
+ */
 const UI_NAME = process.env.REACT_APP_UI_NAME;
 
+/**
+ * UI packaged application path, with generated prefix.
+ * See dotenv config files for updating. See build scripts for generated prefix.
+ *
+ * @type {string}
+ */
 const UI_PATH = process.env.PUBLIC_URL || '/';
 
+/**
+ * UI packaged application version, with generated hash.
+ * See dotenv config files for updating. See build scripts for generated hash.
+ *
+ * @type {string}
+ */
 const UI_VERSION = process.env.REACT_APP_UI_VERSION;
 
 const helpers = {
@@ -65,6 +192,17 @@ const helpers = {
   UI_VERSION
 };
 
+/**
+ * Expose an application specific type.
+ * Associated with access on a browser's developer console.
+ *
+ * @type {{UI_DISABLED_TOOLBAR: boolean, UI_DISPLAY_CONFIG_NAME: string, generateId: function(string): string,
+ *     REVIEW_MODE: boolean, UI_LOGGER_ID: string, UI_DISABLED_GRAPH: boolean, UI_DISPLAY_START_NAME: string,
+ *     UI_DEPLOY_PATH_PREFIX: string, UI_DISPLAY_NAME: string, noopPromise: Promise<{}>, DEV_MODE: boolean,
+ *     TEST_MODE: boolean, noop: Function, isPromise: function((Promise|*)): boolean, UI_PATH: string,
+ *     UI_NAME: string, UI_DISABLED: boolean, UI_DISABLED_TABLE: boolean, UI_VERSION: string, PROD_MODE: boolean,
+ *     noopTranslate: function(string, string): string}}
+ */
 window[UI_LOGGER_ID] = { ...helpers };
 
 export { helpers as default, helpers };

src/components/app.js

@@ -7,12 +7,22 @@ import { I18n } from './i18n/i18n';
 import { Router } from './router/router';
 import Authentication from './authentication/authentication';
 
+/**
+ * Application
+ *
+ * @augments React.Component
+ */
 class App extends React.Component {
   componentDidMount() {
     const { getLocale } = this.props;
     getLocale();
   }
 
+  /**
+   * Render application.
+   *
+   * @returns {Node}
+   */
   render() {
     const { locale } = this.props;
 
@@ -27,22 +37,44 @@ class App extends React.Component {
   }
 }
 
+/**
+ * Prop types.
+ *
+ * @type {{locale: object, getLocale: Function}}
+ */
 App.propTypes = {
   getLocale: PropTypes.func,
   locale: PropTypes.shape({
     value: PropTypes.string
   })
 };
 
+/**
+ * Default props.
+ *
+ * @type {{locale: {}, getLocale: Function}}
+ */
 App.defaultProps = {
   getLocale: helpers.noop,
   locale: {}
 };
 
+/**
+ * Apply actions to props.
+ *
+ * @param {Function} dispatch
+ * @returns {object}
+ */
 const mapDispatchToProps = dispatch => ({
   getLocale: () => dispatch(reduxActions.user.getLocale())
 });
 
+/**
+ * Apply state to props.
+ *
+ * @param {object} state
+ * @returns {object}
+ */
 const mapStateToProps = state => ({ locale: state.user.session.locale });
 
 const ConnectedApp = connectRouter(mapStateToProps, mapDispatchToProps)(App);