RequiredDocParamWithDefault
RequiredDocParamWithDefault
Severity: warning | Type: LiquidHtml
This check reports a parameter a partial declares as required in its {% doc %} tag and then reads through the default filter. Supplying the default is evidence that the partial handles the value being absent, so the declaration almost certainly meant [param].
A parameter is required when its name carries no square brackets: @param {string} name is required, @param {string} [name] is optional.
The {% doc %} tag is the contract, and MissingRenderPartialArguments enforces it as written — so until the declaration says otherwise, every call site that omits the argument is reported for a parameter the partial demonstrably handles. Those call sites cannot fix it; the partial can, and one edit here clears them all at once, along with what hover, completion and platformos-check backfill-docs tell everyone else about the parameter.
The fix is applied automatically: it brackets the name in place and leaves the type and the description untouched. It is safe by construction, since making a parameter optional only widens what a caller may omit.
Only the value the partial defaults counts. In {% assign profile = profile | default: params.profile %} it is profile that the partial handles the absence of; params is merely what it falls back on, and is read precisely when profile is missing, which says nothing about whether params itself may be omitted.
Examples
✗ Incorrect Code Example (Avoid using this):
{% comment %}app/views/partials/forms/upload.liquid{% endcomment %}
{% doc %}
@param {string} name - Name for the input holding the uploaded file URLs
@param {boolean} image_editor_enabled - Whether to enable the image editor
@param {string} aspect_ratio - Aspect ratio for cropping
{% enddoc %}
{% liquid
assign image_editor_enabled = image_editor_enabled | default: false
assign aspect_ratio = aspect_ratio | default: null
%}
Both parameters are declared as required, so {% render 'forms/upload', name: 'photo' %} is reported twice for arguments the partial already handles.
✓ Correct Code Example (Use this instead):
{% doc %}
@param {string} name - Name for the input holding the uploaded file URLs
@param {boolean} [image_editor_enabled] - Whether to enable the image editor
@param {string} [aspect_ratio] - Aspect ratio for cropping
{% enddoc %}
{% liquid
assign image_editor_enabled = image_editor_enabled | default: false
assign aspect_ratio = aspect_ratio | default: null
%}
If the parameter really must be passed, drop the | default fallback instead — keeping both says two different things about the same parameter.
Configuration
The default configuration for this check:
RequiredDocParamWithDefault:
enabled: true
severity: warning
Disabling This Check
This check is advice about a probable mistake rather than a defect in itself, and it is a warning for that reason: requiring a parameter while also defaulting it defensively is unusual, but it is a legitimate choice. Disable it if that is your house style — the call-site checks keep enforcing the contract exactly as declared either way.