Hi Markus,

I don't think the messages are misleading, however the rules here can be hard to follow at first.

My understanding of the updating rules is:
All the updating must be done together as the very last thing to happen.
This means ONLY in the final  'return' statement of the main expression or
defined in the final 'return' statement in functions.
These updating function definitions can only be called in the final statement of the main expression.

The other XQuery rule that applies to your examples is that:
 if there is only one expression in main or a function body then the keyword "return" is omitted

So your first example becomes:

declare %updating function local:add_document($items as item()*)
as empty-sequence()
{
 db:add("Test_DB", $items, "Test.xml")
};

let $my_data as element() := <root><contents>My document</contents></root>
return local:add_document($my_data)

In your second example, you can define the updating function with let, but calling it requires the use of the updating keyword as described in the link you give.

let $my_data as element() := <root><contents>My document</contents></root>,
    $add_document := %updating function($items) {db:add("Test_DB", $items, "Test.xml")}
return (updating $add_document($my_data))

Regards
/Andy

On Wed, 18 May 2022 at 16:05, Markus Elfring <Markus.Elfring@web.de> wrote:
> This aspect of XQuery syntax (when to use commas, when to construct explicit
> sequences with wrapping parens) can be a bit challenging to internalize.

Thanks for your constructive feedback.

I hope that further clarifications will adjust known construction challenges.


>This rework runs for me in the BaseX GUI:

I observed also software behaviour for this adjusted script variant
which is acceptable finally.

* How much were the error messages (which I mentioned for
  the discussed use case) misleading?

* Should the desired document addition work also by the application of
  a corresponding inline function expression?
  https://docs.basex.org/wiki/XQuery_Update#User-Defined_Functions

Regards,
Markus