Merge pull request #3958 from alphagov/rollup-babel-comments

Configure Babel to remove non-public comments

.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',

docs/contributing/coding-standards/js.md

@@ -15,6 +15,8 @@ component
 ```mjs
 /**
  * Component name
+ *
+ * @preserve
  */
 export class Example {
   /**

packages/govuk-frontend/babel.config.js

@@ -11,6 +11,27 @@ 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`
+        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: [
       [
         '@babel/preset-env',

packages/govuk-frontend/src/govuk/components/accordion/accordion.mjs

@@ -14,6 +14,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 extends GOVUKFrontendComponent {
   /** @private */

packages/govuk-frontend/src/govuk/components/button/button.mjs

@@ -7,6 +7,8 @@ const DEBOUNCE_TIMEOUT_IN_SECONDS = 1
 
 /**
  * JavaScript enhancements for the Button component
+ *
+ * @preserve
  */
 export class Button extends GOVUKFrontendComponent {
   /** @private */
@@ -25,7 +27,6 @@ export class Button extends GOVUKFrontendComponent {
   debounceFormSubmitTimer = null
 
   /**
-   *
    * @param {Element} $module - HTML element to use for button
    * @param {ButtonConfig} [config] - Button config
    */

packages/govuk-frontend/src/govuk/components/character-count/character-count.mjs

@@ -13,6 +13,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 extends GOVUKFrontendComponent {
   /** @private */

packages/govuk-frontend/src/govuk/components/checkboxes/checkboxes.mjs

@@ -2,6 +2,8 @@ import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
 
 /**
  * Checkboxes component
+ *
+ * @preserve
  */
 export class Checkboxes extends GOVUKFrontendComponent {
   /** @private */

packages/govuk-frontend/src/govuk/components/error-summary/error-summary.mjs

@@ -6,6 +6,8 @@ import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
  * Error summary component
  *
  * Takes focus on initialisation for accessible announcement, unless disabled in configuration.
+ *
+ * @preserve
  */
 export class ErrorSummary extends GOVUKFrontendComponent {
   /** @private */
@@ -18,7 +20,6 @@ export class ErrorSummary extends GOVUKFrontendComponent {
   config
 
   /**
-   *
    * @param {Element} $module - HTML element to use for error summary
    * @param {ErrorSummaryConfig} [config] - Error summary config
    */

packages/govuk-frontend/src/govuk/components/exit-this-page/exit-this-page.mjs

@@ -5,6 +5,8 @@ import { I18n } from '../../i18n.mjs'
 
 /**
  * Exit This Page component
+ *
+ * @preserve
  */
 export class ExitThisPage extends GOVUKFrontendComponent {
   /** @private */

packages/govuk-frontend/src/govuk/components/header/header.mjs

@@ -2,6 +2,8 @@ import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
 
 /**
  * Header component
+ *
+ * @preserve
  */
 export class Header extends GOVUKFrontendComponent {
   /** @private */

packages/govuk-frontend/src/govuk/components/notification-banner/notification-banner.mjs

@@ -4,6 +4,8 @@ import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
 
 /**
  * Notification Banner component
+ *
+ * @preserve
  */
 export class NotificationBanner extends GOVUKFrontendComponent {
   /** @private */

packages/govuk-frontend/src/govuk/components/radios/radios.mjs

@@ -2,6 +2,8 @@ import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
 
 /**
  * Radios component
+ *
+ * @preserve
  */
 export class Radios extends GOVUKFrontendComponent {
   /** @private */

packages/govuk-frontend/src/govuk/components/skip-link/skip-link.mjs

@@ -2,6 +2,8 @@ import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
 
 /**
  * Skip link component
+ *
+ * @preserve
  */
 export class SkipLink extends GOVUKFrontendComponent {
   /** @private */
@@ -17,7 +19,6 @@ export class SkipLink extends GOVUKFrontendComponent {
   linkedElementListener = false
 
   /**
-   *
    * @param {Element} $module - HTML element to use for skip link
    */
   constructor($module) {

packages/govuk-frontend/src/govuk/components/tabs/tabs.mjs

@@ -2,6 +2,8 @@ import { GOVUKFrontendComponent } from '../../govuk-frontend-component.mjs'
 
 /**
  * Tabs component
+ *
+ * @preserve
  */
 export class Tabs extends GOVUKFrontendComponent {
   /** @private */