LiquidDoc

[benjaminsehl]

Originally posted as issue #1852

Author: Shopify
Expected end date: December 5, 2024

Background

Snippets are the primary method for reusing logic in Liquid. However, their weak interfaces make it easy to overlook dependencies when rendering them.

Is render missing some dependency?

{% render 'article-card',
  article: item,
  show_image: true,
  show_date: section.settings.article_show_date,
  show_author: section.settings.article_show_author,
  media_aspect_ratio: 1,
  lazy_load: lazy_load
%}

It shouldn't be hard to answer this question. Projects such as Dawn have adopted headers as a convention to define such interfaces. This makes it easier to render snippets, as all dependencies are clearly listed, and there is no need to review the entire snippet to check if we're missing a dependency.

{% comment %}
  Renders an article card for a given blog with settings to either show the image or not.

  Accepts:
  - blog: {Object} Blog object
  - article: {Object} Article object
  - media_aspect_ratio: {String} The setting changes the aspect ratio of the article image, if shown
  - media_height: {String} The setting changes the height of the article image. Overrides media_aspect_ratio.
  - show_image: {String} The setting either show the article image or not.
  - show_date: {String} The setting either show the article date or not.
  - show_author: {String} The setting either show the article author or not.
  - show_badge: {String} The setting either show the blog badge or not.
  - lazy_load: {Boolean} Image should be lazy loaded. Default: true (optional)

  Usage:
  {% render 'article-card' blog: blog, article: article, show_image: section.settings.show_image %}
{% endcomment %}

{%- if article and article != empty -%}
  {%- liquid
    assign ratio = 1
    if media_aspect_ratio != null
      assign ratio = media_aspect_ratio
      # ...

While that convention is very helpful, it relies heavily on manual work to keep the list of dependencies updated and to manually check them when rendering.

Proposal

We should officially support these headers in Liquid as documentation, similar to how JSDoc works. This way, tools such as the Liquid language server can support features around these definitions, such as:

• Code completion for snippet parameters (e.g., {% render "icon", █ )
• Code completion for parameters listed in the {% doc %} tag with the proper type inference (thus, for a @param {string} foo, {{ foo |█ }} displays filters for string objects)
• Linting when a {% render ... %} is missing parameters
• Auto-fixing the list of parameters (@param) in the {% doc %} tag (auto-fix means: add missing parameters and remove unused ones)
• Displaying inline documentation when developers hover over {% render ... %} snippets

{% doc %}
  Renders loading-spinner.

  @param {string} foo - some foo
  @param {string} [bar] - optional bar

  @example
  {% render 'loading-spinner', foo: 'foo' %}
  {% render 'loading-spinner', foo: 'foo', bar: 'bar' %}
{% enddoc %}

<div class="{{ bar }} loading__spinner hidden">
  {{ 'loading-spinner-{{ foo }}.svg' | inline_asset_content }}
</div>

The doc tag behaves just like the comment tag but has a special name to be handled differently by Liquid tooling.

Call for suggestions

We welcome any feedback or opinions on this proposal. Please share your thoughts by December 5, 2024. Your input is valuable as we prepare to begin active development on this initiative.

Context

• Investigate bringing back UndefinedObjects for snippets theme-tools#448
• Introduce snippet dependency annotation theme-tools#114