Use jsdoc rules recommended for typescript

.eslintrc.json

@@ -11,7 +11,7 @@
     "extends": [
         "eslint:recommended",
         "plugin:@typescript-eslint/recommended", 
-        "plugin:jsdoc/recommended"
+        "plugin:jsdoc/recommended-typescript"
     ],
     "parser": "@typescript-eslint/parser",
     "parserOptions": {
@@ -30,7 +30,6 @@
         "indent": [
             "off"
         ],
-        "jsdoc/newline-after-description": 0,
         "@typescript-eslint/indent": [
             "error",
             "tab",
@@ -72,7 +71,7 @@
     },
     "overrides": [
         {
-            // also possible in the future to limit to src/client/app/components/**/*.tsx files, where we make sure {} is only used for props.
+            // TODO: Remove this override once these components have been converted to use hooks
             "files": [
                 "src/client/app/components/UIModalComponent.tsx",
                 "src/client/app/containers/admin/CreateUserContainer.tsx",
@@ -149,6 +148,31 @@
                     "as-needed"
                 ]
             }
+        },
+        {
+            // disable jsdoc requirement for reducers and actions
+            "files": [
+                "src/client/app/reducers/*.ts",
+                "src/client/app/actions/*.ts"
+            ],
+            "rules": {
+                "jsdoc/require-jsdoc": "off",
+                "jsdoc/require-returns": "off"
+            }
+        },
+        {
+            // disable jsdoc for containers separately
+            // jsdoc makes sense for containers but we are working on removing them from the codebase
+            // TODO: Remove this override once containers have been converted
+            "files": [
+                "src/client/app/containers/*/*",
+                "src/client/app/containers/*"
+            ],
+            "rules": {
+                "jsdoc/require-jsdoc": "off",
+                "jsdoc/require-returns": "off",
+                "jsdoc/require-param": "off"
+            }
         }
     ]
 }

src/client/app/actions/admin.ts

@@ -15,8 +15,6 @@ import { LanguageTypes } from '../types/redux/i18n';
 import * as moment from 'moment';
 import { AreaUnitType } from '../utils/getAreaUnitConversion';
 
-/* eslint-disable jsdoc/require-jsdoc */
-
 export function updateSelectedMeter(meterID: number): t.UpdateImportMeterAction {
 	return { type: ActionType.UpdateImportMeter, meterID };
 }
@@ -79,7 +77,6 @@ function markPreferencesSubmitted(defaultMeterReadingFrequency: string): t.MarkP
 }
 
 /* eslint-enable */
-/* eslint-disable jsdoc/require-returns*/
 
 /**
  * Dispatches a fetch for admin preferences and sets the state based upon the result
@@ -136,23 +133,21 @@ export function submitPreferences() {
 }
 
 /**
- * @param {State} state The redux state.
- * @returns {boolean} Whether preferences are fetching
+ * @param state The redux state.
+ * @returns Whether preferences are fetching
  */
 function shouldFetchPreferenceData(state: State): boolean {
 	return !state.admin.isFetching;
 }
 
 /**
- * @param {State} state The redux state.
- * @returns {boolean} Whether preferences are submitted
+ * @param state The redux state.
+ * @returns Whether preferences are submitted
  */
 function shouldSubmitPreferenceData(state: State): boolean {
 	return !state.admin.submitted;
 }
 
-/* eslint-disable jsdoc/require-jsdoc */
-
 export function fetchPreferencesIfNeeded(): Thunk {
 	return (dispatch: Dispatch, getState: GetState) => {
 		if (shouldFetchPreferenceData(getState())) {
@@ -176,8 +171,8 @@ function toggleWaitForCikAndDB(): t.ToggleWaitForCikAndDB {
 }
 
 /**
- * @param {State} state The redux state.
- * @returns {boolean} Whether or not the Cik and views are updating
+ * @param state The redux state.
+ * @returns Whether or not the Cik and views are updating
  */
 function shouldUpdateCikAndDBViews(state: State): boolean {
 	return !state.admin.isUpdatingCikAndDBViews;
@@ -186,8 +181,8 @@ function shouldUpdateCikAndDBViews(state: State): boolean {
 /**
  * Redo Cik and/or refresh reading views.
  * This function is called when some changes in units/conversions affect the Cik table or reading views.
- * @param {boolean} shouldRedoCik Whether to refresh Cik.
- * @param {boolean} shouldRefreshReadingViews Whether to refresh reading views.
+ * @param shouldRedoCik Whether to refresh Cik.
+ * @param shouldRefreshReadingViews Whether to refresh reading views.
  */
 export function updateCikAndDBViewsIfNeeded(shouldRedoCik: boolean, shouldRefreshReadingViews: boolean): Thunk {
 	return async (dispatch: Dispatch, getState: GetState) => {

src/client/app/actions/barReadings.ts

@@ -11,12 +11,12 @@ import { readingsApi } from '../utils/api';
 import { BarReadings } from '../types/readings';
 
 /**
- * @param {State} state the Redux state
- * @param {number} meterID the ID of the meter to check
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {moment.Duration} barDuration the duration of each bar for which to check
- * @param {number} unitID the ID of the unit for which to check
- * @returns {boolean} True if the readings for the given meter, time duration, bar length and unit are missing; false otherwise.
+ * @param state the Redux state
+ * @param meterID the ID of the meter to check
+ * @param timeInterval the interval over which to check
+ * @param barDuration the duration of each bar for which to check
+ * @param unitID the ID of the unit for which to check
+ * @returns True if the readings for the given meter, time duration, bar length and unit are missing; false otherwise.
  */
 export function shouldFetchMeterBarReadings(state: State, meterID: number, timeInterval: TimeInterval,
 	barDuration: moment.Duration, unitID: number): boolean {
@@ -47,12 +47,12 @@ export function shouldFetchMeterBarReadings(state: State, meterID: number, timeI
 }
 
 /**
- * @param {State} state the Redux state
- * @param {number} groupID the ID of the group to check
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {moment.Duration} barDuration the duration of each bar for which to check
- * @param {number} unitID the ID of the unit for which to check
- * @returns {boolean} True if the readings for the given group, time duration, bar length and unit are missing; false otherwise.
+ * @param state the Redux state
+ * @param groupID the ID of the group to check
+ * @param timeInterval the interval over which to check
+ * @param barDuration the duration of each bar for which to check
+ * @param unitID the ID of the unit for which to check
+ * @returns True if the readings for the given group, time duration, bar length and unit are missing; false otherwise.
  */
 export function shouldFetchGroupBarReadings(state: State, groupID: number, timeInterval: TimeInterval,
 	barDuration: moment.Duration, unitID: number): boolean {
@@ -82,58 +82,57 @@ export function shouldFetchGroupBarReadings(state: State, groupID: number, timeI
 	return !readingsForUnit.isFetching;
 }
 
-/* eslint-disable jsdoc/require-returns */
 
 /**
- * @param {number} meterIDs the IDs of the meters to get readings
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {moment.Duration} barDuration the duration of each bar for which to check
- * @param {number} unitID the ID of the unit for which to check
+ * @param meterIDs the IDs of the meters to get readings
+ * @param timeInterval the interval over which to check
+ * @param barDuration the duration of each bar for which to check
+ * @param unitID the ID of the unit for which to check
  */
 export function requestMeterBarReadings(meterIDs: number[], timeInterval: TimeInterval, barDuration: moment.Duration,
 	unitID: number): t.RequestMeterBarReadingsAction {
 	return { type: ActionType.RequestMeterBarReadings, meterIDs, timeInterval, barDuration, unitID };
 }
 
 /**
- * @param {number} groupIDs the IDs of the groups to get readings
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {moment.Duration} barDuration the duration of each bar for which to check
- * @param {number} unitID the ID of the unit for which to check
+ * @param groupIDs the IDs of the groups to get readings
+ * @param timeInterval the interval over which to check
+ * @param barDuration the duration of each bar for which to check
+ * @param unitID the ID of the unit for which to check
  */
 export function requestGroupBarReadings(groupIDs: number[], timeInterval: TimeInterval, barDuration: moment.Duration,
 	unitID: number): t.RequestGroupBarReadingsAction {
 	return { type: ActionType.RequestGroupBarReadings, groupIDs, timeInterval, barDuration, unitID };
 }
 
 /**
- * @param {number} meterIDs the IDs of the meters to get readings
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {moment.Duration} barDuration the duration of each bar for which to check
- * @param {number} unitID the ID of the unit for which to check
- * @param {BarReadings} readings the readings for the given meters
+ * @param meterIDs the IDs of the meters to get readings
+ * @param timeInterval the interval over which to check
+ * @param barDuration the duration of each bar for which to check
+ * @param unitID the ID of the unit for which to check
+ * @param readings the readings for the given meters
  */
 export function receiveMeterBarReadings(meterIDs: number[], timeInterval: TimeInterval, barDuration: moment.Duration,
 	unitID: number, readings: BarReadings): t.ReceiveMeterBarReadingsAction {
 	return { type: ActionType.ReceiveMeterBarReadings, meterIDs, timeInterval, unitID, barDuration, readings };
 }
 
 /**
- * @param {number} groupIDs the IDs of the groups to get readings
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {moment.Duration} barDuration the duration of each bar for which to check
- * @param {number} unitID the ID of the unit for which to check
- * @param {BarReadings} readings the readings for the given groups
+ * @param groupIDs the IDs of the groups to get readings
+ * @param timeInterval the interval over which to check
+ * @param barDuration the duration of each bar for which to check
+ * @param unitID the ID of the unit for which to check
+ * @param readings the readings for the given groups
  */
 export function receiveGroupBarReadings(groupIDs: number[], timeInterval: TimeInterval, barDuration: moment.Duration,
 	unitID: number, readings: BarReadings): t.ReceiveGroupBarReadingsAction {
 	return { type: ActionType.ReceiveGroupBarReadings, groupIDs, timeInterval, barDuration, unitID, readings };
 }
 
 /**
- * @param {number} meterIDs the IDs of the meters to get readings
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {number} unitID the ID of the unit for which to check
+ * @param meterIDs the IDs of the meters to get readings
+ * @param timeInterval the interval over which to check
+ * @param unitID the ID of the unit for which to check
  */
 function fetchMeterBarReadings(meterIDs: number[], timeInterval: TimeInterval, unitID: number): Thunk {
 	return async (dispatch: Dispatch, getState: GetState) => {
@@ -145,9 +144,9 @@ function fetchMeterBarReadings(meterIDs: number[], timeInterval: TimeInterval, u
 }
 
 /**
- * @param {number} groupIDs the IDs of the groups to get readings
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {number} unitID the ID of the unit for which to check
+ * @param groupIDs the IDs of the groups to get readings
+ * @param timeInterval the interval over which to check
+ * @param unitID the ID of the unit for which to check
  */
 function fetchGroupBarReadings(groupIDs: number[], timeInterval: TimeInterval, unitID: number): Thunk {
 	return async (dispatch: Dispatch, getState: GetState) => {
@@ -160,8 +159,8 @@ function fetchGroupBarReadings(groupIDs: number[], timeInterval: TimeInterval, u
 
 /**
  * Fetches readings for the bar chart of all selected meters and groups, if needed.
- * @param {TimeInterval} timeInterval the interval over which to check
- * @param {number} unitID the ID of the unit for which to check
+ * @param timeInterval the interval over which to check
+ * @param unitID the ID of the unit for which to check
  */
 export function fetchNeededBarReadings(timeInterval: TimeInterval, unitID: number): Thunk {
 	return (dispatch: Dispatch, getState: GetState) => {