Merge pull request #362 from oogali/jsdoc-linting

ESLint rule enforcement for JSDoc

.eslintrc.js

@@ -12,6 +12,7 @@ module.exports = {
     'plugin:react-hooks/recommended',
     'plugin:jsx-a11y/recommended',
     'plugin:storybook/recommended',
+    'plugin:jsdoc/recommended',
   ],
   overrides: [{
     files: ['*.js', '*.mjs', '*.jsx'],
@@ -33,6 +34,7 @@ module.exports = {
     'import',
     'react',
     'jsx-a11y',
+    'jsdoc',
   ],
   rules: {
     'import/newline-after-import': ['error', {count: 2}],
@@ -83,12 +85,25 @@ module.exports = {
     'func-call-spacing': ['error', 'never'],
     'no-multiple-empty-lines': ['error', {max: 2, maxEOF: 1}],
     'react/jsx-closing-bracket-location': 'error',
+    'valid-jsdoc': 'off',
+    'jsdoc/newline-after-description': 'error',
+    'jsdoc/check-types': 'error',
+    'jsdoc/require-param-description': 'off',
+    'jsdoc/require-returns-description': 'off',
+    'jsdoc/check-param-names': 'off',
+    'jsdoc/require-param': 'off',
+    'jsdoc/require-param-type': 'off',
     'require-await': 'error',
   },
   settings: {
     react: {
       version: '17.0.2',
     },
+    jsdoc: {
+      tagNamePreference: {
+        'returns': 'return',
+      },
+    },
   },
   reportUnusedDisableDirectives: true,
 }

package.json

@@ -76,6 +76,7 @@
     "eslint-config-google": "^0.14.0",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-jest-dom": "^4.0.2",
+    "eslint-plugin-jsdoc": "^39.3.6",
     "eslint-plugin-jsx-a11y": "^6.6.1",
     "eslint-plugin-react": "^7.30.1",
     "eslint-plugin-react-hooks": "^4.6.0",

src/BaseRoutes.jsx

@@ -22,8 +22,8 @@ import debug from './utils/debug'
  *   http://host/share/v/gh/bldrs-ai/Share/main/public/index.ifc
  *
  * @see https://github.com/bldrs-ai/Share/wiki/Design#ifc-scene-load
- * @param {testElt} For unit test allow use of a stub here instead of loading the app.
- * @return {Object}
+ * @param {React.Component} testElt For unit test allow use of a stub here instead of loading the app.
+ * @return {object}
  */
 export default function BaseRoutes({testElt = null}) {
   const location = useLocation()

src/BaseRoutesMock.test.jsx

@@ -11,9 +11,9 @@ test('mockRoutes', () => {
 
 
 /**
- * @param {array} initialEntries For react-routrer MemoryRouter.
- * @param {Object} contentElt React component for Route.
- * @return {Object} React component
+ * @param {Array} initialEntries For react-router MemoryRouter.
+ * @param {object} contentElt React component for Route.
+ * @return {React.Component} React component
  */
 export default function MockRoutes({initialEntries = ['/'], contentElt} = {}) {
   // TODO(pablo): would be better to not include the initialEntries

src/Components/AboutControl.jsx

@@ -15,8 +15,9 @@ import GitHubIcon from '../assets/2D_Icons/GitHub.svg'
 
 /**
  * Button to toggle About panel on and off
+ *
  * @param {string} installPrefix For use in static asset links.
- * @return {Object} The AboutControl react component.
+ * @return {object} The AboutControl react component.
  */
 export default function AboutControl({installPrefix}) {
   const [isDialogDisplayed, setIsDialogDisplayed] =
@@ -48,10 +49,11 @@ export default function AboutControl({installPrefix}) {
 
 /**
  * The AboutDialog component
+ *
  * @param {boolean} isDialogDisplayed
- * @param {function} setIsDialogDisplayed
+ * @param {Function} setIsDialogDisplayed
  * @param {string} installPrefix node
- * @return {Component} React component
+ * @return {React.Component} React component
  */
 function AboutDialog({isDialogDisplayed, setIsDialogDisplayed, installPrefix}) {
   return (
@@ -67,8 +69,9 @@ function AboutDialog({isDialogDisplayed, setIsDialogDisplayed, installPrefix}) {
 
 /**
  * The content portion of the AboutDialog
+ *
  * @param {string} installPrefix node
- * @return {Object} React component
+ * @return {object} React component
  */
 function AboutContent({installPrefix}) {
   const classes = useStyles()

src/Components/Alert.jsx

@@ -9,10 +9,10 @@ import CheckIcon from '@mui/icons-material/Check'
 
 
 /**
- * @param {function} onCloseCb
+ * @param {Function} onCloseCb
  * @param {string} title
  * @param {string} message
- * @return {Object} React component
+ * @return {object} React component
  */
 export default function Alert({onCloseCb, title = 'Oops', message}) {
   const [isOpen, setIsOpen] = useState(true)

src/Components/BaseGroup.jsx

@@ -7,10 +7,11 @@ import SampleModelsControl from './SampleModelsControl'
 
 /**
  * Base group contains Settings, ModelUpload, About
+ *
  * @param {string} installPrefix Serving prefix for the app, for use in
  * constructing static asset links.
- * @param {Object} fileOpen ItemPanel component
- * @return {Object} React component
+ * @param {object} fileOpen ItemPanel component
+ * @return {object} React component
  */
 export default function BaseGroup({installPrefix, fileOpen}) {
   const classes = useStyles()

src/Components/Buttons.jsx

@@ -9,12 +9,12 @@ import {assertDefined} from '../utils/assert'
 
 /**
  * @param {string} title Tooltip text
- * @param {function} onClick
- * @param {Object} icon
+ * @param {Function} onClick
+ * @param {object} icon
  * @param {string} placement
  * @param {string} size Size of button component
  * @param {string} dataTestId Internal attribute for component testing
- * @return {Object} React component
+ * @return {React.Component} React component
  */
 export const TooltipIconButton = ({
   title,
@@ -40,12 +40,12 @@ export const TooltipIconButton = ({
 
 
 /**
- * @param {function} onClick
+ * @param {Function} onClick
  * @param {string} title Tooltip text
- * @param {Object} icon
+ * @param {object} icon
  * @param {string} size Size of button component
  * @param {string} placement Default: left
- * @return {Object} React component
+ * @return {React.Component} React component
  */
 export function TooltipToggleButton({
   onClick,
@@ -84,12 +84,12 @@ export function TooltipToggleButton({
 /**
  * @param {string} title The text for tooltip
  * @param {boolean} isDialogDisplayed
- * @param {function} setIsDialogDisplayed
- * @param {Object} icon The header icon
+ * @param {Function} setIsDialogDisplayed
+ * @param {object} icon The header icon
  * @param {string} placement Default: left
  * @param {string} size Size of button component
- * @param {Object} dialog The controlled dialog
- * @return {Object} React component
+ * @param {object} dialog The controlled dialog
+ * @return {React.Component} React component
  */
 export function ControlButton({
   title,
@@ -124,12 +124,13 @@ export function ControlButton({
 /**
  * A FormButton is a TooltipIconButton but with parameterized type for
  * form actions.
+ *
  * @param {string} title
- * @param {Object} icon
+ * @param {object} icon
  * @param {string} type Type of button (and icon to render)
  * @param {string} placement Placement of tooltip
  * @param {string} size Size of button component
- * @return {Object} React component
+ * @return {React.Component} React component
  */
 export function FormButton({title, icon, type = 'submit', placement = 'left', size = 'medium'}) {
   assertDefined(title, icon)
@@ -148,12 +149,13 @@ export function FormButton({title, icon, type = 'submit', placement = 'left', si
 /**
  * A FormButton is a TooltipIconButton but with parameterized type for
  * form actions.
+ *
  * @param {string} title
- * @param {Object} icon
+ * @param {object} icon
  * @param {string} type Type of button (and icon to render)
  * @param {string} placement Placement of tooltip
  * @param {string} size Size of button component
- * @return {Object} React component
+ * @return {React.Component} React component
  */
 export function RectangularButton({
   title,

src/Components/CameraControl.jsx

@@ -21,9 +21,9 @@ import {roundCoord} from '../utils/math'
  * URL hash and sets the camera position, as well as adds a hash
  * listener to do the same whenever the hash changes.
  *
- * @param {Object} viewer The IFC viewer, which contains the
+ * @param {object} viewer The IFC viewer, which contains the
  *   cameraControls
- * @return {Object} React component
+ * @return {object} React component
  */
 export default function CameraControl({viewer}) {
   assertDefined(viewer, viewer.IFC, viewer.IFC.context, viewer.IFC.context.ifcCamera)
@@ -53,8 +53,9 @@ export const CAMERA_PREFIX = 'c'
 /**
  * Set camera position from window location hash and add listener for
  * hash change.
- * @param {Object} location Either window.location or react-router location
- * @param {Object} cameraControls obtained from the viewer
+ *
+ * @param {object} location Either window.location or react-router location
+ * @param {object} cameraControls obtained from the viewer
  */
 function onLoad(location, cameraControls) {
   debug().log('CameraControl#onLoad')
@@ -66,8 +67,9 @@ function onLoad(location, cameraControls) {
 /**
  * Sets the camera position to the coordinate encoded in the URL
  * hash if it is present
- * @param {Object} location window.location
- * @param {Object} cameraControls obtained from the viewer
+ *
+ * @param {object} location window.location
+ * @param {object} cameraControls obtained from the viewer
  */
 export function onHash(location, cameraControls) {
   const encodedParams = getHashParams(location, CAMERA_PREFIX)
@@ -80,8 +82,9 @@ export function onHash(location, cameraControls) {
 
 /**
  * Set the camera position
- * @param {String} encodedParams camera position
- * @param {Object} cameraControls obtained from the viewer
+ *
+ * @param {string} encodedParams camera position
+ * @param {object} cameraControls obtained from the viewer
  */
 export function setCameraFromParams(encodedParams, cameraControls) {
   // addCameraUrlParams is accessed from the issue card and it is undefined on the first render
@@ -109,7 +112,7 @@ const paramRegex = new RegExp(paramPattern)
 // Exported for testing
 /**
  * @param {string} encodedParams
- * @return {Object|undefined} The coordinates if present and valid else undefined
+ * @return {object|undefined} The coordinates if present and valid else undefined
  */
 export function parseHashParams(encodedParams) {
   const match = encodedParams.match(paramRegex)
@@ -151,7 +154,8 @@ export function hasValidUrlParams() {
 
 /**
  * Adds camera coords to url.
- * @param {Object} cameraControls obtained from the viewer
+ *
+ * @param {object} cameraControls obtained from the viewer
  */
 export function addCameraUrlParams(cameraControls) {
   // addCameraUrlParams is accessed from the issue card and it is undefined on the first render

src/Components/CameraControl.test.jsx

@@ -51,12 +51,12 @@ test('onHash, target', () => {
 /** Mocks the IFCjs camera. */
 class MockCamera {
   /**
-   * @param {Number} x
-   * @param {Number} y
-   * @param {Number} z
-   * @param {Number} tx
-   * @param {Number} ty
-   * @param {Number} tz
+   * @param {number} x
+   * @param {number} y
+   * @param {number} z
+   * @param {number} tx
+   * @param {number} ty
+   * @param {number} tz
    * @param {boolean} doTween
    */
   constructor(x = 0, y = 0, z = 0, tx = 0, ty = 0, tz = 0, doTween = false) {
@@ -71,10 +71,10 @@ class MockCamera {
 
 
   /**
-   * @param {Number} x
-   * @param {Number} y
-   * @param {Number} z
-   * @param {Boolean} doTween
+   * @param {number} x
+   * @param {number} y
+   * @param {number} z
+   * @param {boolean} doTween
    */
   setPosition(x, y, z, doTween) {
     this.x = x
@@ -101,10 +101,10 @@ class MockCamera {
 
 
   /**
-   * @param {Number} tx
-   * @param {Number} ty
-   * @param {Number} tz
-   * @param {Boolean} doTween
+   * @param {number} tx
+   * @param {number} ty
+   * @param {number} tz
+   * @param {boolean} doTween
    */
   setTarget(tx, ty, tz, doTween) {
     this.tx = tx

src/Components/Dialog.jsx

@@ -10,13 +10,14 @@ import {assertDefined} from '../utils/assert'
 
 /**
  * A generic base dialog component.
- * @param {Object} icon Leading icon above header description
+ *
+ * @param {object} icon Leading icon above header description
  * @param {string} headerText Short message describing the operation
  * @param {boolean} isDialogDisplayed
- * @param {function} setIsDialogDisplayed
- * @param {Object} clazzes Optional classes
- * @param {Object} content node
- * @return {Object} React component
+ * @param {Function} setIsDialogDisplayed
+ * @param {object} clazzes Optional classes
+ * @param {object} content node
+ * @return {object} React component
  */
 export default function Dialog({
   icon,

src/Components/Dialog_redesign.jsx

@@ -13,11 +13,12 @@ import InputBar from './InputBar'
 
 /**
  * A generic base dialog component.
+ *
  * @param {string} headerContent Short message describing the operation
  * @param {string} bodyContent
  * @param {boolean} isDialogDisplayed
- * @param {function} setIsDialogDisplayed
- * @return {Object} React component
+ * @param {Function} setIsDialogDisplayed
+ * @return {object} React component
  */
 export default function Dialog({
   headerContent,
@@ -46,7 +47,8 @@ export default function Dialog({
 
 /**
  * Content for the open Dialog
- * @return {Object} React component
+ *
+ * @return {object} React component
  */
 export function OpenDialogBodyContent() {
   const classes = useStyles(useTheme())
@@ -79,7 +81,8 @@ export function OpenDialogBodyContent() {
 
 /**
  * Title for the open Dialog
- * @return {Object} React component
+ *
+ * @return {object} React component
  */
 export function OpenDialogHeaderContent() {
   const classes = useStyles(useTheme())