Support documenting individual macro arguments

[chrisp60]

Currently, you cannot add comments to individual macro arguments.

Current Example

{# This is fine #}
{% macro foo(bar, baz) -%}
 Foo is {{ bar }} and {{ baz }}
{%- endmacro %}

Featured Example

{# This is no good #}
{% macro foo(
    {# Describes foo #}
    bar,
    {# Describes more of foo #}
    baz
) -%}
 Foo is {{ bar }} and {{ baz }}
{%- endmacro %}

Why

Macros for large projects can grow to have many arguments, and the ability to document arguments can be a net positive.

Where

I originally requested this feature in rinja-rs/rinja#273, a consumer of jinja syntax in the rust ecosystem.

Maintainers agreed it would be nice, countering with the understandable concern of being incompatible with jinja itself. They asked me to bring it up here, just to gauge interest.

How

Skimming some of the parsing code, this seems like it would be a pain to implement. I would understand if the request is declined.

To be entirely honest, I do not have much experience in python and am unsure if I could reasonably implement it myself. Totally understand if this just isn't worth it.

[dorsma]

How about putting a comment at the top of the macro that describes what it does along with its arguments, similar to Python docstrings? This way keeps the macro signature clean, and there's no need to modify the template engine.

Example using Google style args:

{% macro foo(bar, baz) -%}
    {# 
    Describes foo

    Args:
        bar: Describes bar
        baz: Describes baz
    #}
    Foo is {{ bar }} and {{ baz }}
{%- endmacro %}