[Oorexx-users] Method arguments and documentation

[Staffan T. <sta...@gm...>]

Quite some time ago I made some comments on the use of place-holding commas
in parameter lists and the way they are documented. I didn't receive any
reaction on this at the time (maybe something went wrong with my posting)
and I forgot about it until now when I looked at the following description
of the createStaticText method:

>>--createStaticText(-+------+--x-,--y-+------+-+------+-+----------+-+--------+-)-><
                      +-id-,-+         +-,-cx-+ +-,-cy-+ +-,-style--+
+-,-text-+

This in my opinion is a good example that illustrates the confusion that
can be created when reading it. The lower line identifies the optional
parameters but what I react on here is that the commas are listed there as
well. If I strictly follow this to create a static text object without a
resource ID, I would write it like this:

createStaticText(posX, posY, posCX, posCY, myStyle, myText)

But without testing it I think that the correct coding should be:

createStaticText(, posX, posY, posCX, posCY, myStyle, myText)

In the same way the following method call should be correct as well
according to the doc, but of course it isn't:

createStaticText(posX, posY, myText)

Based on this I am of the opinion that the parameter list is better
documented like this:

>>--createStaticText(-+----+-,-x-,-y-,-+----+-,-+----+-,-+-------+-,-+------+-)-><
                      +-id-+           +-cx-+   +-cy-+   +-style-+
+-text-+

Here there are no optional commas, which is the norm when writing a
parameter list. There are exceptions to this, like the ListView 'add'
method, which allows for a variable number of commas, but such exceptions
are few and the variable comma seems to be documented "correctly".

What's the general view on this?

Staffan