Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support to LiquidDoc with the new {% doc %} tag #1895

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

karreiro
Copy link
Contributor

@karreiro karreiro commented Jan 16, 2025

This PR implements RFC#1865 and introduces support for the new {% doc %} tag, which will be used to document elements of Liquid templates, primarily snippets.

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

By adopting the emerging pattern of using headers on these snippets, the {% doc %} tag will document those interfaces. This way, tools such as the Liquid language server can support features around these definitions, such as code completion, better linting rules, and inline documentation. Here's an example of {% doc %} in action:

{% 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>

This new tag should behave just like the {% comment %} tag and have no effect on rendering. Therefore, to implement this, the Doc tag inherits from Comment, similar to how Unless inherits from If.

Comment on lines +27 to +28
class Doc < Comment
TAG_NAME = "doc"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the weird things about comment is that you can nest them. Do we really want similar behaviour for doc? I don't think we do 🤔?

@bakura10
Copy link

bakura10 commented Jan 16, 2025

{{ 'loading-spinner-{{ foo }}.svg' |

Is this a typo? Since when such an awesome syntax is possible ? 😍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants