Request: Allow comments on macro arguments

[chrisp60]

I am using git main

Admittedly, this use case is derived from a somewhat degenerate pattern.

I can define this macro...

{% macro input(name, value = "") %}
   <input name="{{ name }}" value="{{ value }}">
{% endmacro input %}

This fails to compile...

{% macro input(
    {# the name attribute of the input #}
    name, 
    value = "",
) %}
   <input name="{{ name }}" value="{{ value }}">
{% endmacro input %}

The error provided is...
error: expected ) to close macro argument list
The error correctly points to the issue.

My use case for wanting this feature is the below macro definition. I have to make a substantial amount of user forms for my project.

{% macro input(
  name, 
  value = "", 
  label = "",
  prefix = "",
  kind = "text",
  autocomplete = "",
  required = false,
  div = "col-md-12 col-lg-4",
  attrs = "",
  ...[plus many more]
) %}

Why I am requesting this

• It would be convenient
• I would not have to parse through the actual macro body to see how each argument is used.

Why this may not be a good feature

• You cannot comment arguments in normal rust code.
• You could just comment the macro itself (then you would need to ensure it is synced to the macro body).
• It may not be common for users to have macros with substantial amounts of arguments.
• It could be a maintenance burden.
• At some point, just use a normal rust builder pattern (like bon or typed_builder)
• EDIT: as mentioned by the project owner, jinja itself does not support it

I would not at all be disappointed if this was rejected. If approved, I could attempt an implementation

[GuillaumeGomez]

Problem here is that you want to be able add a delimiter inside a delimiter, which is not allowed in the jinja syntax. I agree it would be nice to be able to add docs on arguments, but in this case, it'd make rinja not compliant with jinja.

[chrisp60]

Yeah that is not something I did not even begin to consider. Up to you if you want to leave this up as a possibility for the future.

I imagine the compatibility is something you would prefer to keep. I am inclined to believe you if you say it just isn't possible.

[GuillaumeGomez]

If jinja officially supports adding comments inside jinja blocks, then I'm fine adding it too. Please propose it on jinja directly.

[Kijewski]

One can always add the comments before or inside the macro:

{#
  Macro to generate an HTML `<input>` element.
  Arguments:
  * `name` [string]: that is submitted in a POST request
  * `value` [string, optional]: prefilled value
#}
{% macro input(name, value = "") %}
   <input name="{{ name }}" value="{{ value }}">
{% endmacro input %}

{% macro input(name, value = "") %}
  {#
    Macro to generate an HTML `<input>` element.
    Arguments:
    * `name` [string]: key that is submitted in a POST request
    * `value` [string, optional]: pre-filled value
  #}
   <input name="{{ name }}" value="{{ value }}">
{% endmacro input %}

Actually, I find this much more readable than writing the comments in-between the lines. In rust you wouldn't write ↓ either:

/// Function to generate an HTML `<input>` element.
fn input(
  /// key that is submitted in a POST request
  name: &str,
  /// pre-filled value
  value: Option<&str>,
) -> String {…}

Actually, I don't know if this is valid code, and if so, what rustdoc would make of it.

[GuillaumeGomez]

It's not valid code since you can't put attributes on function arguments. ;)

[chrisp60]

If jinja officially supports adding comments inside jinja blocks, then I'm fine adding it too. Please propose it on jinja directly.

Will do. Once I get around to it I will reference it back to this issue. Thank you for the consideration.

[GuillaumeGomez]

Thanks! Waiting to hear from it then.