Issues found on page 'CREATE MACRO Statement'

[rpbouman]

Suggesting some points of improvement:

1. Today (not sure since what version exacctly), parameters may be typed. But this is rather under-documented. It is mentioned once and very superficially in the examples of the Scalar Macros section: https://duckdb.org/docs/current/sql/statements/create_macro#scalar-macros

2. I believe the parameter syntax in the the syntax diagram is wrong:

• the param-name and param-name := default-value appear as if in a required succession, while they really should be alternatives
• there is no mention of the optional type declaration for the parameter
• the current diagram suggests the parameter list plus the AS-clause can be repeteated. This repetition should apply to the parameter declarations

3. The default value feature is also under documented:

• it should mention that parameters declarations with defaults cannot be declared before parameter declarations without defaults.

4. There ought to be something that explains assigning values to named parameters when calling the macro. In particular, it should explicitly explain the assignment operator :=. This is the only correct way to assign values to macro parameters, while built-in functions with named parameters may also support plain '='. This can be a real gotcha, especially when passing parameters from one macro to the next, because an expression like a = a is still valid - it's just that it evaluates to TRUE rather than assigning the value of the a parameter from the outer macro to the a parameter of the macro being called. For example:

create macro m1(arg1 boolean := false) as 
(select arg1);

create macro m2(arg1) as 
(select m1(arg1 = arg1));

select macro m2(false); 
-- result is TRUE because in the definition of m2, 
-- the result of comparing the argument with itself (arg1 = arg1 ) is passed into m1
-- rather than assigning the value of m2's arg1 to m1's arg1

Page URL: https://duckdb.org/docs/current/sql/statements/create_macro.html

[rpbouman]

I know this is quite a lot. I can give it a stab if you like? Let me know. I don't know how to create the syntax diagrams though.