Open charlespwd opened 10 months ago
👋🏻 there's a second part to this that would be extremely helpful for theme developers; checking what values for params are available.
While knowing if a param of type {String}
is fine, knowing what string values can be passed is even better. Something like:
{%- comment -%}
Some kind of snippet that outputs an image of different sizes
@param {Object} image - Image object
@param {'33'|'50'|'66'} media_width - Width of the media
{%- endcomment -%}
The syntax here is based on JSDoc's specification for type unions. Not sure if the formatting is the most optimal in a Liquid context, but it's an idea.
There are also other things we can check for. For example, auto-completion of {Boolean}
values should populate and check for true/false
values, and should result in an error for anything other than these two values. I'm sure there are things we can do with the {Object}
that will further help with the developer experience as well.
Yeah I think https://github.com/Shopify/theme-tools/issues/114 wants to address just that. Hard to prioritize right now but definitely still something on our radar :)
Some thoughts on the matter:
The parameters should be defined anywhere in the file. Since there are no functions or the like in liquid, the developer should be free to declare them wherever they see fit.
The return type should also be declarable. While the returned content will always be a string, we should still be able to describe what that string represents.
At least one line per parameter. The developer should have enough space to describe parameters without stuffing them all into one line as much of the theme code I have seen unfortunately does.
It should be possible to break a parameter declaration over multiple lines. To make the declaration more readable, the developer should have the option to break the description over multiple lines.
@Keyword <Parameter> { <Type } <Description>
The keyword to declare the parameter should be case insensitive and multiple spaces between parts be treated indifferently. Versatile syntax, less arbitrary restrictions.
Have a way to specify the with
( default ) parameter.
-> @With
? ( case insensitive as mentioned before )
Valid syntax examples: ( I chose 'input' as the keyword )
{%- liquid
#
# @With { String } Message for something or other
# @input Flavor { 'Vanilla' , 'Chocolate' }
# @Input isTasty {Boolean} Is it tasty?
# @INPUT IS-EXTREME { Boolean } EXTREME PARAMETERS
# @Input Multiline_Description { String }
# Describes a parameter on multiple
# lines, where every next line
# that isn't empty, not a comment
# or another declaration is part of it.
#
-%}
{% comment %}
@Ouput Something you have been waiting for.
{% endcomment %}
Wrote this on my phone, now my fingers hurt~ [ Edit ] Added some more later on
Is your feature request related to a problem? Please describe. A new look at https://github.com/Shopify/theme-tools/issues/448
When you type
{% render 'snippet', arg1: some_value %}
, we don't check that that snippet needs thatarg1
variable, nor do we do reliably reportUndefinedObject
in the snippet.Describe the solution you'd like I'd like something that helps folks on both ends.
Describe alternatives you've considered
{% # global arg1, arg2, arg3 %}
comment at the top of the file