FR: Add @param comment syntax in template IDE hints

[mikemartin]

I've been experimenting with a convention for props in Antlers partials using the view frontmatter. It would be useful to extend templates IDE hints with a comment syntax like the example below.

{{ partial:button type="primary" size="large" }}

{{#
   @name Button
   @param bool someBool This is just a normal parameter that'd show up in auto-complete.
   @param @from view:types type The button type.
   @param @from view:sizes size The button size.
#}}
---
classes: 'flex w-full sm:inline-flex items-center justify-center py-2 px-4 rounded-full border border-transparent text-base font-medium focus:outline-none focus:ring-4 focus:ring-opacity-50'
sizes:
  large: 'sm:text-lg sm:py-3 sm:px-5'
types:
  primary: 'text-white bg-primary-500 hover:bg-primary-400 focus:ring-primary-600'
  secondary: 'text-secondary-900 bg-secondary-100 hover:bg-secondary-50 focus:ring-secondary-200 dark:text-white dark:bg-secondary-800 dark:hover:bg-secondary-700 dark:focus:ring-secondary-900'
  disabled: 'text-gray-400 bg-gray-200 dark:text-white dark:bg-secondary-800 dark:opacity-75 cursor-not-allowed'
---

<button type=submit"
class="{{ view }}{{ classes }} {{ sizes[size] }} {{ types[type] }}{{/view}}">...</button>

[mikemartin]

@JohnathonKoster Adding your comment from Discord for reference:

I like the self-contained nature of it. I'd have to do some experimenting, but since the information is there in the partial's front-matter - that is something that could reasonably be parsed out to provide suggestions for users. Would have to play around and come up with a comment syntax that is comfortable (an extension to https://antlers.dev/docs/template-ide-hints#template-and-partial-names-and-descriptions). Something like:

{{#
@ name Button
@ param bool someBool This is just a normal parameter that'd show up in auto-complete.
@ param @ from view:types type The button type.
@ param @ from view:sizes size The button size.
#}}

Where @ param @ from would pull in all the first-level values from the referenced field such as primary, secondary and present those as options to the user within VS Code. Would need to think on it, though.

Edit: added spaces to not at-mention a ton of GitHub usernames on accident -JK (Thank you! MM)

[JohnathonKoster]

@mikemartin

The final syntax to make this work is:

---
classes: 'flex w-full sm:inline-flex items-center justify-center py-2 px-4 rounded-full border border-transparent text-base font-medium focus:outline-none focus:ring-4 focus:ring-opacity-50'
sizes:
  large: 'sm:text-lg sm:py-3 sm:px-5'
types:
  primary: 'text-white bg-primary-500 hover:bg-primary-400 focus:ring-primary-600'
  secondary: 'text-secondary-900 bg-secondary-100 hover:bg-secondary-50 focus:ring-secondary-200 dark:text-white dark:bg-secondary-800 dark:hover:bg-secondary-700 dark:focus:ring-secondary-900'
  disabled: 'text-gray-400 bg-gray-200 dark:text-white dark:bg-secondary-800 dark:opacity-75 cursor-not-allowed'
---
{{#
   @name Button
   @param bool someBool This is just a normal parameter that'd show up in auto-complete.
   @param @front types type The button type.
   @param @front sizes size The button size.
#}}
<button type=submit"
class="{{ view }}{{ classes }} {{ sizes[size] }} {{ types[type] }}{{/view}}">...</button>

[JohnathonKoster]

It drops the view: prefix in favor of a front directive, and requires that the comment comes after the YAML front matter