Improve component documentation

app/views/govuk_publishing_components/components/docs/layout_for_public.yml

@@ -69,35 +69,39 @@ examples:
         <h2 class="govuk-heading-l">This is a title</h2>
         <p class="govuk-body">This is some body text with <a href="https://example.com">a link</a>.
   with_account_layout_but_without_account_feedback_footer:
+    description: The account layout renders with an account-specific feedback banner by default. This flag allows this banner to be omitted.
     data:
       show_account_layout: true
       omit_account_feedback_footer: true
       block: |
         <h2 class="govuk-heading-l">This is a title</h2>
         <p class="govuk-body">This is some body text with <a href="https://example.com">a link</a>.</p>
   with_current_account_navigation:
-    description: "Valid options are currently `your-account`, `manage`, and `security`"
+    description: "The account layout renders with an account-specific nav to help users navigate different areas of their account. This flag is here to allow control over which option in the nav is highlighted as `current`. Valid options are currently `your-account`, `manage`, and `security`."
     data:
       show_account_layout: true
       account_nav_location: "manage"
       block: |
         <h2 class="govuk-heading-l">This is a title</h2>
-        <p class="govuk-body">This is some body text with <a href="https://example.com">a link</a>.</p>
+        <p class="govuk-body">This is a page under the "Manage your account" section, so we must highlight "Manage your account" in the account navigation.</p>
   with_account_layout_but_without_account_navigation:
+    description: The account layout renders with account navigation by default, this hides it.
     data:
       show_account_layout: true
       omit_account_navigation: true
       block: |
         <h2 class="govuk-heading-l">This is a title</h2>
         <p class="govuk-body">This is some body text with <a href="https://example.com">a link</a>.</p>
   with_account_layout_but_without_account_phase_banner:
+    description: The account layout renders with a phase banner by default, this hides it.
     data:
       show_account_layout: true
       omit_account_phase_banner: true
       block: |
         <h2 class="govuk-heading-l">This is a title</h2>
         <p class="govuk-body">This is some body text with <a href="https://example.com">a link</a>.</p>
   with_custom_cookie_banner:
+    description: Passes content through to the [cookie banner component](/component-guide/cookie_banner/).
     data:
       cookie_banner_data:
         title: Can we use cookies to collect information about how you use GOV.UK?