Lint, highlight and complete snippet signatures

[charlespwd]

Is your feature request related to a problem? Please describe.
A new look at #448

When you type {% render 'snippet', arg1: some_value %}, we don't check that that snippet needs that arg1 variable, nor do we do reliably report UndefinedObject in the snippet.

Describe the solution you'd like
I'd like something that helps folks on both ends.

• In the snippet file, you can make sure that you specify the dependencies you need and then we autocomplete them as though they were defined in that file.
• At the call site, if variables are required, then a linting error is shown if the render statement doesn't have the required arguments.
• Documented standard

Describe alternatives you've considered

• a {% # global arg1, arg2, arg3 %} comment at the top of the file
• Piggy-backing on the convention used in dawn for snippets. There's a syntax that they use to define what variables are available.

[bertiful]

👋🏻 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.

[charlespwd]

Yeah I think #114 wants to address just that. Hard to prioritize right now but definitely still something on our radar :)

[PhoneDroid]

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

[charlespwd]

We're now tracking this by Request for suggestions: LiquidDoc Shopify/liquid#1852
and the downstream issues we'll create for it