Update perlfunc.pod saying that there are things we don't document!

[jidanni]

For #22214.

[iabyn]

I'm opposed to this proposed doc change. It doesn't seem to add anything of value to the docs for 'my'.

[jidanni]

I'm just saying that in the docs it should say that there's some stuff purposely not documented.

[leonerd]

Most (good) programming languages are like sets of Lego bricks - a nice collection of reusable parts that can be stuck together in almost infinite different combinations to achieve any kind of result. It is beyond hope to expect that any documentation can possibly talk about all possible ways to stick the bricks together. Good documentation gives a nice list of the possible bricks that are available, and explains how those bricks, individually, interact with others. With a well-designed system it should then be possible for users to interepret from those descriptions how any particular combination of bricks should behave.

We already explain - in detail - the individual push and my bricks. We really don't need to explicitly call out the behaviour of the combination of the two, any more than we might decide to explain that you can combine numerical addition and my, in such cases as my $four = (my $three = 3) + (my $one = 1);. The behaviour of this naturally falls out from the basic operation of my and numerical addition. The same principle applies here.

[mauke]

Just because some combination of syntax/features is not listed with an explicit example, does not mean it is not documented. For example, if the documentation says "two numbers can be added with the + operator" (even without giving any specific examples), that does not mean that the behavior of code like 42 + 6.5 is "purposely not documented".

In this particular instance, calling push my @bar, @baz a "shortcut" is particularly weird, since the same effect can be obtained in a shorter (and IMHO clearer) way by writing my @bar = @baz. The reason we don't list this kind of code in our examples is not because it is "too easy for the user to mess up", but because it is silly. Similarly, the analogous case of initializing scalars is shown as my $x = 42 and not my $x //= 42, even though the latter would work fine.

[karenetheridge]

Perhaps we just need to be clearer that these functions operate on lvalues; and then any use of an lvalue (such as my @foo = ...) can be safely inferred without a specific mention.