Clean up JS comments to be aligned to JSDoc where suitable

CHANGELOG.txt

@@ -26,6 +26,7 @@ Changelog
  * Maintenance: Avoid redundant `ALLOWED_HOSTS` check in `Site.find_for_request` (Jake Howard)
  * Maintenance: Update `CloneController` to ensure that `added`/`cleared` events are not dispatched as cancelable (LB (Ben) Johnston)
  * Maintenance: Remove unused `uuid` UMD module as all code is now using the NPM module (LB (Ben) Johnston)
+ * Maintenance: Clean up JS comments throughout codebase to be aligned to JSDoc where practical (LB (Ben) Johnston)
 
 
 6.3 LTS (01.11.2024)

client/src/api/client.js

@@ -14,8 +14,11 @@ const checkStatus = (response) => {
 
 const parseJSON = (response) => response.json();
 
-// Response timeout cancelling the promise (not the request).
-// See https://github.com/github/fetch/issues/175#issuecomment-216791333.
+/**
+ * Response timeout cancelling the promise (not the request).
+ *
+ * @see https://github.com/github/fetch/issues/175#issuecomment-216791333.
+ */
 const timeout = (ms, promise) => {
   const race = new Promise((resolve, reject) => {
     const timeoutId = setTimeout(() => {

client/src/components/ChooserWidget/ImageChooserWidget.js

@@ -11,12 +11,21 @@ export class ImageChooser extends Chooser {
     );
   }
 
+  /**
+   * Constructs the initial state of the chooser from the rendered (static) HTML.
+   * The state is either null (no image chosen) or an object containing the image details.
+   *
+   * @returns {Object|null} The initial state of the chooser. If an image is chosen,
+   * the state object contains the following properties:
+   * - id: {number} The ID of the chosen image.
+   * - edit_url: {string} The URL to edit the chosen image.
+   * - title: {string} The title of the chosen image.
+   * - preview: {Object} An object containing the preview details of the chosen image:
+   *   - url: {string} The URL of the preview image.
+   *   - width: {string} The width of the preview image.
+   *   - height: {string} The height of the preview image.
+   */
   getStateFromHTML() {
-    /*
-    Construct initial state of the chooser from the rendered (static) HTML.
-    State is either null (= no image chosen) or a dict of id, edit_url, title
-    and preview (= a dict of url, width, height).
-    */
     const state = super.getStateFromHTML();
     if (state) {
       state.preview = {

client/src/components/ChooserWidget/index.js

@@ -210,8 +210,10 @@ export class ChooserFactory {
     this.modal.open(options, callback);
   }
 
+  /**
+   * retrieve the widget object corresponding to the given HTML ID
+   */
   getById(id) {
-    /* retrieve the widget object corresponding to the given HTML ID */
     return document.getElementById(`${id}-chooser`).widget;
   }
 }

client/src/components/ComboBox/ComboBox.tsx

@@ -114,8 +114,10 @@ export default function ComboBox<ComboBoxOption extends ComboBoxItem>({
       }
     },
 
-    // For not re-setting and not removing focus from combobox when pressing `Alt+Tab`
-    // to switch windows.
+    /**
+     * For not re-setting and not removing focus from combobox when pressing `Alt+Tab`
+     * to switch windows.
+     */
     stateReducer: (state, actionAndChanges) => {
       const { type, changes } = actionAndChanges;
       switch (type) {

client/src/components/InlinePanel/index.js

@@ -40,9 +40,11 @@ export class InlinePanel extends ExpandingFormset {
     });
   }
 
+  /**
+   * Update states of listing controls in response to a change of state such as
+   * adding, deleting or moving an element.
+   */
   updateControlStates() {
-    /* Update states of listing controls in response to a change of state such as
-    adding, deleting or moving an element */
     this.updateChildCount();
     this.updateMoveButtonDisabledStates();
     this.updateAddButtonState();

client/src/components/StreamField/blocks/BaseSequenceBlock.js

@@ -382,12 +382,14 @@ export class BaseSequenceChild extends EventEmitter {
   }
 }
 
+/**
+ * Base class for controls that appear between blocks in a sequence, to allow inserting new
+ * blocks at that point. Subclasses should render an HTML structure with a single root element
+ * (replacing the placeholder passed to the constructor) and set it as this.element.
+ * When the user requests to insert a block, we call onRequestInsert passing the index number
+ * and a dict of control-specific options.
+ */
 export class BaseInsertionControl {
-  /* Base class for controls that appear between blocks in a sequence, to allow inserting new
-  blocks at that point. Subclasses should render an HTML structure with a single root element
-  (replacing the placeholder passed to the constructor) and set it as this.element.
-  When the user requests to insert a block, we call onRequestInsert passing the index number
-  and a dict of control-specific options. */
   constructor(placeholder, opts) {
     this.index = opts && opts.index;
     this.onRequestInsert = opts && opts.onRequestInsert;
@@ -465,10 +467,11 @@ export class BaseSequenceBlock {
     });
   }
 
-  blockCountChanged() {
-    /* Called whenever the block count has changed; subclasses can override this to apply
-    checks on max block count and disable insert / duplicate controls accordingly */
-  }
+  /**
+   * Called whenever the block count has changed; subclasses can override this to apply
+   * checks on max block count and disable insert / duplicate controls accordingly.
+   */
+  blockCountChanged() {}
 
   _insert(childBlockDef, initialState, id, index, opts) {
     const prefix = this.prefix + '-' + this.blockCounter;

client/src/components/StreamField/blocks/ListBlock.js

@@ -15,10 +15,10 @@ import {
 
 /* global $ */
 
+/**
+ * Wrapper for an item inside a ListBlock
+ */
 class ListChild extends BaseSequenceChild {
-  /*
-  wrapper for an item inside a ListBlock
-  */
   getState() {
     return {
       id: this.id,
@@ -50,12 +50,13 @@ class ListChild extends BaseSequenceChild {
   }
 }
 
+/**
+ * Represents a position in the DOM where a new list item can be inserted.
+ *
+ * @description
+ * This renders a + button. Later, these could also be used to represent drop zones for drag+drop reordering.
+ */
 class InsertPosition extends BaseInsertionControl {
-  /*
-  Represents a position in the DOM where a new list item can be inserted.
-
-  This renders a + button. Later, these could also be used to represent drop zones for drag+drop reordering.
-  */
   constructor(placeholder, opts) {
     super(placeholder, opts);
     this.onRequestInsert = opts && opts.onRequestInsert;
@@ -135,20 +136,23 @@ export class ListBlock extends BaseSequenceBlock {
     }
   }
 
+  /**
+   * State for a ListBlock is a list of {id, value} objects, but
+   * ListBlock.insert accepts the value as first argument; id is passed in the options dict instead.
+   */
   setState(blocks) {
-    // State for a ListBlock is a list of {id, value} objects, but
-    // ListBlock.insert accepts the value as first argument; id is passed in the options dict instead.
     this.clear();
     blocks.forEach(({ value, id }, i) => {
       this.insert(value, i, { id: id || uuidv4() });
     });
   }
 
+  /**
+   * Called when an 'insert new block' action is triggered: given a dict of data from the insertion control,
+   * return the block definition and initial state to be used for the new block.
+   * For a ListBlock, no data is passed from the insertion control, as there is a single fixed child block definition.
+   */
   _getChildDataForInsertion() {
-    /* Called when an 'insert new block' action is triggered: given a dict of data from the insertion control,
-    return the block definition and initial state to be used for the new block.
-    For a ListBlock, no data is passed from the insertion control, as there is a single fixed child block definition.
-    */
     const blockDef = this.blockDef.childBlockDef;
     const initialState = this.blockDef.initialChildState;
     return [blockDef, initialState];
@@ -180,7 +184,7 @@ export class ListBlock extends BaseSequenceBlock {
     return new InsertPosition(placeholder, opts);
   }
 
-  /*
+  /**
    * Called whenever a block is added or removed
    *
    * Updates the state of add / duplicate block buttons to prevent too many blocks being inserted.

client/src/components/StreamField/blocks/StreamBlock.js

@@ -26,10 +26,11 @@ import {
 /* global $ */
 
 class StreamChild extends BaseSequenceChild {
-  /*
-  wrapper for a block inside a StreamBlock, handling StreamBlock-specific metadata
-  such as id
-  */
+  /**
+   * wrapper for a block inside a StreamBlock, handling StreamBlock-specific metadata
+   * such as id
+   * @returns {Object} - The state of the child block
+   */
   getState() {
     return {
       type: this.type,
@@ -255,9 +256,8 @@ export class StreamBlock extends BaseSequenceBlock {
     this.childBlockCounts.set(type, currentBlockCount);
   }
 
-  /*
+  /**
    * Called whenever a block is added or removed
-   *
    * Updates the state of add / duplicate block buttons to prevent too many blocks being inserted.
    */
   blockCountChanged() {
@@ -355,11 +355,13 @@ export class StreamBlock extends BaseSequenceBlock {
     return this._insert(childBlockDef, value, id, index, opts);
   }
 
+  /**
+   * Called when an 'insert new block' action is triggered: given a dict of data from the insertion control.
+   * For a StreamBlock, the dict of data consists of 'type' (the chosen block type name, as a string).
+   *
+   * @returns {Array} - The block definition, initial state, and id for the new block
+   */
   _getChildDataForInsertion({ type }) {
-    /* Called when an 'insert new block' action is triggered: given a dict of data from the insertion control,
-    return the block definition and initial state to be used for the new block.
-    For a StreamBlock, the dict of data consists of 'type' (the chosen block type name, as a string).
-    */
     const blockDef = this.blockDef.childBlockDefsByName[type];
     const initialState = this.blockDef.initialChildStates[type];
     return [blockDef, initialState, uuidv4()];

client/src/entrypoints/admin/telepath/widgets.js

@@ -224,13 +224,15 @@ class Select extends Widget {
 }
 window.telepath.register('wagtail.widgets.Select', Select);
 
+/**
+ * Definition for a command in the Draftail context menu that inserts a block.
+ *
+ * @param {BoundDraftailWidget} widget - the bound Draftail widget
+ * @param {Object} blockDef - block definition for the block to be inserted
+ * @param {Object} addSibling - capability descriptors from the containing block's capabilities definition
+ * @param {Object} split - capability descriptor from the containing block's capabilities definition
+ */
 class DraftailInsertBlockCommand {
-  /* Definition for a command in the Draftail context menu that inserts a block.
-   * Constructor args:
-   * widget - the bound Draftail widget
-   * blockDef - block definition for the block to be inserted
-   * addSibling, split - capability descriptors from the containing block's capabilities definition
-   */
   constructor(widget, blockDef, addSibling, split) {
     this.widget = widget;
     this.blockDef = blockDef;
@@ -286,12 +288,13 @@ class DraftailInsertBlockCommand {
   }
 }
 
+/**
+ * Definition for a command in the Draftail context menu that inserts a block.
+ *
+ * @param {BoundDraftailWidget} widget - the bound Draftail widget
+ * @param {Object} split - capability descriptor from the containing block's capabilities definition
+ */
 class DraftailSplitCommand {
-  /* Definition for a command in the Draftail context menu that splits the block.
-   * Constructor args:
-   * widget - the bound Draftail widget
-   * split - capability descriptor from the containing block's capabilities definition
-   */
   constructor(widget, split) {
     this.widget = widget;
     this.split = split;

client/src/entrypoints/admin/workflow-action.js

@@ -11,7 +11,10 @@ function addHiddenInput(form, name, val) {
 // eslint-disable-next-line no-underscore-dangle
 window._addHiddenInput = addHiddenInput;
 
-/* When a workflow action button is clicked, either show a modal or make a POST request to the workflow action view */
+/**
+ * When a workflow action button is clicked,
+ * either show a modal or make a POST request to the workflow action view
+ */
 function ActivateWorkflowActionsForDashboard() {
   const workflowActionElements = document.querySelectorAll(
     '[data-workflow-action-url]',

docs/releases/6.4.md

@@ -46,6 +46,7 @@ depth: 1
  * Avoid redundant `ALLOWED_HOSTS` check in `Site.find_for_request` (Jake Howard)
  * Update `CloneController` to ensure that `added`/`cleared` events are not dispatched as cancelable (LB (Ben) Johnston)
  * Remove unused `uuid` UMD module as all code is now using the NPM module (LB (Ben) Johnston)
+ * Clean up JS comments throughout codebase to be aligned to JSDoc where practical (LB (Ben) Johnston)
 
 
 ## Upgrade considerations - changes affecting all projects

prettier.config.js

@@ -1,5 +1,5 @@
 /**
- * See https://prettier.io/docs/en/options.html.
+ * @see https://prettier.io/docs/en/options.html
  */
 module.exports = {
   arrowParens: 'always',