diff --git a/packages/govuk-frontend/src/govuk/components/checkboxes/options/params.mjs b/packages/govuk-frontend/src/govuk/components/checkboxes/options/params.mjs
index 4b9a5c352a..693fab992a 100644
--- a/packages/govuk-frontend/src/govuk/components/checkboxes/options/params.mjs
+++ b/packages/govuk-frontend/src/govuk/components/checkboxes/options/params.mjs
@@ -140,6 +140,7 @@ export const params = [
           {
             name: 'html',
             type: 'string',
+            required: true,
             description: 'The HTML to reveal when the checkbox is checked'
           }
         ]
diff --git a/packages/govuk-frontend/src/govuk/components/radios/options/params.mjs b/packages/govuk-frontend/src/govuk/components/radios/options/params.mjs
index 695cf8c448..f65bee15db 100644
--- a/packages/govuk-frontend/src/govuk/components/radios/options/params.mjs
+++ b/packages/govuk-frontend/src/govuk/components/radios/options/params.mjs
@@ -125,6 +125,7 @@ export const params = [
           {
             name: 'html',
             type: 'string',
+            required: true,
             description: 'The HTML to reveal when the radio is checked'
           }
         ]
diff --git a/packages/govuk-frontend/src/govuk/components/summary-list/options/params.mjs b/packages/govuk-frontend/src/govuk/components/summary-list/options/params.mjs
index e332fe87b8..263302dfc9 100644
--- a/packages/govuk-frontend/src/govuk/components/summary-list/options/params.mjs
+++ b/packages/govuk-frontend/src/govuk/components/summary-list/options/params.mjs
@@ -26,7 +26,9 @@ export const params = [
       {
         name: 'key.html',
         type: 'string',
-        required: true
+        required: true,
+        description:
+          'If `text` is set, this is not required. HTML to use within the each key. If `html` is provided, the `text` option will be ignored.'
       },
       {
         name: 'key.classes',
diff --git a/shared/lib/components.js b/shared/lib/components.js
index 797f9ec927..c60a3b280b 100644
--- a/shared/lib/components.js
+++ b/shared/lib/components.js
@@ -89,17 +89,17 @@ module.exports = {
 }
 
 /**
- * Component data from YAML
+ * Component data
  *
  * @typedef {object} ComponentData
- * @property {ComponentOption[]} [params] - Nunjucks macro options
- * @property {ComponentExample[]} [examples] - Example Nunjucks macro options
+ * @property {ComponentOption[]} params - Nunjucks macro options (or params)
+ * @property {ComponentExample[]} examples - Examples of Nunjucks macro options (or params)
  * @property {string} [previewLayout] - Nunjucks layout for component preview
  * @property {string} [accessibilityCriteria] - Accessibility criteria
  */
 
 /**
- * Component option from YAML
+ * Nunjucks macro option (or param)
  *
  * @typedef {object} ComponentOption
  * @property {string} name - Option name
@@ -111,10 +111,12 @@ module.exports = {
  */
 
 /**
- * Component example from YAML
+ * Example of Nunjucks macro options (or params)
  *
  * @typedef {object} ComponentExample
  * @property {string} name - Example name
- * @property {object} data - Example data
+ * @property {string} [description] - Example description
+ * @property {string[]} [previewLayoutModifiers] - Component preview layout class modifiers
  * @property {boolean} [hidden] - Example hidden from review app
+ * @property {object} data - Example data
  */