From 1be2036893cba947ebe2647175edca247b8234cc Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Thu, 13 Jul 2023 15:38:38 +0100
Subject: [PATCH 1/4] Allow JSDoc tag `@preserve` to prevent comment removal

---
 .eslintrc.js | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/.eslintrc.js b/.eslintrc.js
index 41cd1bdd9e..ebea964db1 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -43,11 +43,6 @@ module.exports = {
           }
         ],
 
-        // JSDoc blocks are optional
-        'jsdoc/require-jsdoc': 'off',
-        'jsdoc/require-param-description': 'off',
-        'jsdoc/require-param': 'off',
-
         // Check for valid formatting
         'jsdoc/check-line-alignment': [
           'warn',
@@ -57,6 +52,19 @@ module.exports = {
           }
         ],
 
+        // JSDoc blocks can use `@preserve` to prevent removal
+        'jsdoc/check-tag-names': [
+          'warn',
+          {
+            definedTags: ['preserve']
+          }
+        ],
+
+        // JSDoc blocks are optional
+        'jsdoc/require-jsdoc': 'off',
+        'jsdoc/require-param-description': 'off',
+        'jsdoc/require-param': 'off',
+
         // Require hyphens before param description
         // Aligns with TSDoc style: https://tsdoc.org/pages/tags/param/
         'jsdoc/require-hyphen-before-param-description': 'warn',

From 31e81d40058a54380459b354a2ace88980f7fa62 Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Tue, 8 Aug 2023 15:31:22 +0100
Subject: [PATCH 2/4] Configure Babel to remove all private and internal
 comments

But allow the `@preserve` tag to prevent removal
---
 packages/govuk-frontend/babel.config.js | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/packages/govuk-frontend/babel.config.js b/packages/govuk-frontend/babel.config.js
index 2d139979f1..a33c13ba06 100644
--- a/packages/govuk-frontend/babel.config.js
+++ b/packages/govuk-frontend/babel.config.js
@@ -11,6 +11,19 @@ module.exports = function (api) {
   const browserslistEnv = isBrowser ? 'javascripts' : 'node'
 
   return {
+    generatorOpts: {
+      shouldPrintComment(comment) {
+        if (!isBrowser || comment.includes('* @preserve')) {
+          return true
+        }
+
+        // Assume all comments are public unless
+        // tagged with `@private` or `@internal`
+        return ['* @internal', '* @private'].every(
+          (tag) => !comment.includes(tag)
+        )
+      }
+    },
     presets: [
       [
         '@babel/preset-env',

From 389472bf9d919293f033073f7ff95ab8050cd4dc Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Fri, 28 Jul 2023 14:40:28 +0100
Subject: [PATCH 3/4] Configure Babel to remove developer comments

---
 packages/govuk-frontend/babel.config.js | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/govuk-frontend/babel.config.js b/packages/govuk-frontend/babel.config.js
index a33c13ba06..c1b79e7172 100644
--- a/packages/govuk-frontend/babel.config.js
+++ b/packages/govuk-frontend/babel.config.js
@@ -19,9 +19,17 @@ module.exports = function (api) {
 
         // Assume all comments are public unless
         // tagged with `@private` or `@internal`
-        return ['* @internal', '* @private'].every(
-          (tag) => !comment.includes(tag)
+        const isPrivate = ['* @internal', '* @private'].some((tag) =>
+          comment.includes(tag)
         )
+
+        // Flag any JSDoc comments worth keeping
+        const isDocumentation = ['* @param', '* @returns', '* @typedef'].some(
+          (tag) => comment.includes(tag)
+        )
+
+        // Print only public JSDoc comments
+        return !isPrivate && isDocumentation
       }
     },
     presets: [

From 7f668a56f691bd91c0eac21d09526231aed7168d Mon Sep 17 00:00:00 2001
From: Colin Rotherham <work@colinr.com>
Date: Fri, 28 Jul 2023 15:10:33 +0100
Subject: [PATCH 4/4] Add JSDoc tag `@preserve` to component classes

---
 docs/contributing/coding-standards/js.md                       | 2 ++
 .../src/govuk/components/accordion/accordion.mjs               | 2 ++
 packages/govuk-frontend/src/govuk/components/button/button.mjs | 3 ++-
 .../src/govuk/components/character-count/character-count.mjs   | 2 ++
 .../src/govuk/components/checkboxes/checkboxes.mjs             | 2 ++
 .../src/govuk/components/error-summary/error-summary.mjs       | 3 ++-
 .../src/govuk/components/exit-this-page/exit-this-page.mjs     | 2 ++
 packages/govuk-frontend/src/govuk/components/header/header.mjs | 2 ++
 .../components/notification-banner/notification-banner.mjs     | 2 ++
 packages/govuk-frontend/src/govuk/components/radios/radios.mjs | 2 ++
 .../src/govuk/components/skip-link/skip-link.mjs               | 3 ++-
 packages/govuk-frontend/src/govuk/components/tabs/tabs.mjs     | 2 ++
 12 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/contributing/coding-standards/js.md b/docs/contributing/coding-standards/js.md
index 13b1e20c90..06931b7bdf 100644
--- a/docs/contributing/coding-standards/js.md
+++ b/docs/contributing/coding-standards/js.md
@@ -15,6 +15,8 @@ component
 ```mjs
 /**
  * Component name
+ *
+ * @preserve
  */
 export class Example {
   /**
diff --git a/packages/govuk-frontend/src/govuk/components/accordion/accordion.mjs b/packages/govuk-frontend/src/govuk/components/accordion/accordion.mjs
index 4123160d32..378cd09a77 100644
--- a/packages/govuk-frontend/src/govuk/components/accordion/accordion.mjs
+++ b/packages/govuk-frontend/src/govuk/components/accordion/accordion.mjs
@@ -13,6 +13,8 @@ import { I18n } from '../../i18n.mjs'
  *
  * The state of each section is saved to the DOM via the `aria-expanded`
  * attribute, which also provides accessibility.
+ *
+ * @preserve
  */
 export class Accordion {
   /** @private */
diff --git a/packages/govuk-frontend/src/govuk/components/button/button.mjs b/packages/govuk-frontend/src/govuk/components/button/button.mjs
index b1204dbfc2..45d6b88e8c 100644
--- a/packages/govuk-frontend/src/govuk/components/button/button.mjs
+++ b/packages/govuk-frontend/src/govuk/components/button/button.mjs
@@ -6,6 +6,8 @@ const DEBOUNCE_TIMEOUT_IN_SECONDS = 1
 
 /**
  * JavaScript enhancements for the Button component
+ *
+ * @preserve
  */
 export class Button {
   /** @private */
@@ -24,7 +26,6 @@ export class Button {
   debounceFormSubmitTimer = null
 
   /**
-   *
    * @param {Element} $module - HTML element to use for button
    * @param {ButtonConfig} [config] - Button config
    */
diff --git a/packages/govuk-frontend/src/govuk/components/character-count/character-count.mjs b/packages/govuk-frontend/src/govuk/components/character-count/character-count.mjs
index 3e4b46c4f5..f3b0e3f854 100644
--- a/packages/govuk-frontend/src/govuk/components/character-count/character-count.mjs
+++ b/packages/govuk-frontend/src/govuk/components/character-count/character-count.mjs
@@ -12,6 +12,8 @@ import { I18n } from '../../i18n.mjs'
  *
  * You can configure the message to only appear after a certain percentage
  * of the available characters/words has been entered.
+ *
+ * @preserve
  */
 export class CharacterCount {
   /** @private */
diff --git a/packages/govuk-frontend/src/govuk/components/checkboxes/checkboxes.mjs b/packages/govuk-frontend/src/govuk/components/checkboxes/checkboxes.mjs
index 2ceb333905..4b9210995b 100644
--- a/packages/govuk-frontend/src/govuk/components/checkboxes/checkboxes.mjs
+++ b/packages/govuk-frontend/src/govuk/components/checkboxes/checkboxes.mjs
@@ -1,5 +1,7 @@
 /**
  * Checkboxes component
+ *
+ * @preserve
  */
 export class Checkboxes {
   /** @private */
diff --git a/packages/govuk-frontend/src/govuk/components/error-summary/error-summary.mjs b/packages/govuk-frontend/src/govuk/components/error-summary/error-summary.mjs
index db034725e7..250e1ad639 100644
--- a/packages/govuk-frontend/src/govuk/components/error-summary/error-summary.mjs
+++ b/packages/govuk-frontend/src/govuk/components/error-summary/error-summary.mjs
@@ -5,6 +5,8 @@ import { normaliseDataset } from '../../common/normalise-dataset.mjs'
  * Error summary component
  *
  * Takes focus on initialisation for accessible announcement, unless disabled in configuration.
+ *
+ * @preserve
  */
 export class ErrorSummary {
   /** @private */
@@ -17,7 +19,6 @@ export class ErrorSummary {
   config
 
   /**
-   *
    * @param {Element} $module - HTML element to use for error summary
    * @param {ErrorSummaryConfig} [config] - Error summary config
    */
diff --git a/packages/govuk-frontend/src/govuk/components/exit-this-page/exit-this-page.mjs b/packages/govuk-frontend/src/govuk/components/exit-this-page/exit-this-page.mjs
index 09e25ab51a..79771ce3d9 100644
--- a/packages/govuk-frontend/src/govuk/components/exit-this-page/exit-this-page.mjs
+++ b/packages/govuk-frontend/src/govuk/components/exit-this-page/exit-this-page.mjs
@@ -4,6 +4,8 @@ import { I18n } from '../../i18n.mjs'
 
 /**
  * Exit This Page component
+ *
+ * @preserve
  */
 export class ExitThisPage {
   /** @private */
diff --git a/packages/govuk-frontend/src/govuk/components/header/header.mjs b/packages/govuk-frontend/src/govuk/components/header/header.mjs
index 13d692ad48..8d667192ca 100644
--- a/packages/govuk-frontend/src/govuk/components/header/header.mjs
+++ b/packages/govuk-frontend/src/govuk/components/header/header.mjs
@@ -1,5 +1,7 @@
 /**
  * Header component
+ *
+ * @preserve
  */
 export class Header {
   /** @private */
diff --git a/packages/govuk-frontend/src/govuk/components/notification-banner/notification-banner.mjs b/packages/govuk-frontend/src/govuk/components/notification-banner/notification-banner.mjs
index bfd1bca269..67d192fbf4 100644
--- a/packages/govuk-frontend/src/govuk/components/notification-banner/notification-banner.mjs
+++ b/packages/govuk-frontend/src/govuk/components/notification-banner/notification-banner.mjs
@@ -3,6 +3,8 @@ import { normaliseDataset } from '../../common/normalise-dataset.mjs'
 
 /**
  * Notification Banner component
+ *
+ * @preserve
  */
 export class NotificationBanner {
   /** @private */
diff --git a/packages/govuk-frontend/src/govuk/components/radios/radios.mjs b/packages/govuk-frontend/src/govuk/components/radios/radios.mjs
index aaccf0dced..95bbb9d417 100644
--- a/packages/govuk-frontend/src/govuk/components/radios/radios.mjs
+++ b/packages/govuk-frontend/src/govuk/components/radios/radios.mjs
@@ -1,5 +1,7 @@
 /**
  * Radios component
+ *
+ * @preserve
  */
 export class Radios {
   /** @private */
diff --git a/packages/govuk-frontend/src/govuk/components/skip-link/skip-link.mjs b/packages/govuk-frontend/src/govuk/components/skip-link/skip-link.mjs
index 45466f757b..da3a3e3c4c 100644
--- a/packages/govuk-frontend/src/govuk/components/skip-link/skip-link.mjs
+++ b/packages/govuk-frontend/src/govuk/components/skip-link/skip-link.mjs
@@ -1,5 +1,7 @@
 /**
  * Skip link component
+ *
+ * @preserve
  */
 export class SkipLink {
   /** @private */
@@ -15,7 +17,6 @@ export class SkipLink {
   linkedElementListener = false
 
   /**
-   *
    * @param {Element} $module - HTML element to use for skip link
    */
   constructor($module) {
diff --git a/packages/govuk-frontend/src/govuk/components/tabs/tabs.mjs b/packages/govuk-frontend/src/govuk/components/tabs/tabs.mjs
index 54e1295e5f..75c4b8225e 100644
--- a/packages/govuk-frontend/src/govuk/components/tabs/tabs.mjs
+++ b/packages/govuk-frontend/src/govuk/components/tabs/tabs.mjs
@@ -1,5 +1,7 @@
 /**
  * Tabs component
+ *
+ * @preserve
  */
 export class Tabs {
   /** @private */