Infer section schema types via LiquidDoc

[davidwarrington]

As per our chat on Discord it would be really nice if in LiquidDoc we had access to a global type that can infer schemas from other sections.

For example this would infer the type from the sections/collection-filters.liquid schema rather than the author having to create a custom type themselves (when that's eventually possible).

{% comment %}
Accepts:
- section: {Section<'collection-filters'>}
{% endcomment %}

It would also be safer if the schema changes as the type will automatically reflect it.

The syntax is borrowed from TypeScript as that's what I'm familiar with.

[panoply]

Following this up from discord because when I begin writing the capability, discord is a huge pain to find historical conversations.

---

Maybe @muchisx has a point here:

Given the novice appealing nature of Liquid and the general development level of folks, I don't know how many people are comfortable or even aware of Type annotations, which begs to ask the question whether dot . notation targeting is a better option? I mean, considering we are dealing with JSON like structures, maybe devs would feel more at home?

Personally, I am far more inclined to achieve and using TypeScript inspired syntax, as per @davidwarrington initial approaches:

---

If we take into consideration projects like jsdocs and sassdoc both of these use overlapping syntaxes or ones which correlate to some degree. I think @davidwarrington was on target with moving to an @ prefix. Boycotting the Liquid Doc syntacticals that were initially introduced in Dawn, opens up for more possibility.

Anyway, moving on and getting to the approach we should take.

1. Should we enforce an upper case?
2. Should there be different syntax for file specific targeting vs. object property

Example of file-specific targeting

The <''> syntax should only be for file-specific targeting.

Section<'filename'>

Example of Object property specific targeting

The . dot notation should only be for object property targeting.

Product.variants

Examples

Based on chats we have been having in discord, I think it boils down to these 2 (as a starting point). Of course, I am very much open to ideas/thoughts.

Option 1

Below we use . notation when targeting section blocks, roughly based on what @davidwarrington has already put forward.

{% comment %}

@accepts
- bar: Section<'filename'>
- qux: Section<'filename', 'setting-name'>
- foo: Section.Blocks<'filename', 'type-name'>
- baz: Product.variants

{% endcomment %}

Option 2 (Sections)

Below is based on @muchisx suggestion here, which feels a tad extraneous tbh, but maybe easier for folks to apply?

{% comment %}

@accepts
- bar: Section<'filename'>
- qux: Section<'filename', 'setting.name'>
- foo: Section <'filename', ['blocks']['type']['type-name']>
- baz: Product.variants

{% endcomment %}

[muchisx]

how about a combination of both?

 Section<'filename'>.Blocks<'type-name'>

This would be assuming that the Section object would always be referenced with the filename and the Block object will always be referenced with type-name.

It's arbitrary, since both objects have other properties that could be used for filtering but these are usually the ones used by Liquid devs.

When you render a section within liquid you use the section liquid tag, and that used the filename and when you want to target a specific block in liquid you use a case tag inside a for tag and you filter by block.type.

So it should be intuitive for developers even if arbitrary?

[panoply]

Making some action on this one. We will adopt the . dot notation syntax structure, for example:

{% comment %}

@accepts
- bar: Section<'filename'>
- qux: Section<'filename', 'setting-name'>
- foo: Section.Blocks<'filename', 'type-name'>
- baz: Product.variants

{% endcomment %}

Completions will only be made available for folks who adopt the @ prefix structures, which is better and hopefully moves developers to stop using the Dawn approach. I'll upstream formatting support for @usage (which will instead use @example) in Æsthetic for beautification.

I'll need to write up a specific guide and ruleset, hoping someone can help with that.

[panoply]

This will come in v4.1 - You can track the progress in #186 - Will update as it progresses.