[doc] Add a disclaimer about using //= and ||= in signatures with earlier Perl versions

[vaitkus]

Where

https://perldoc.perl.org/perlsub#Signatures

Description

Certain examples given in the Signatures section raise syntax errors when run under earlier Perl versions. Namely, the

sub foo ($name //= "world") {
    print "Hello, $name";
}

foo(undef);  # will print "Hello, world"

and

sub foo ($x ||= 10) {
    return 5 + $x;
}

examples work properly under Perl v5.38.2, but raise the following syntax error under Perl v5.36.0:

Illegal operator following parameter in a subroutine signature at signatures-test.pl line X, near "($name //= "world""

Note, that other signature usage examples seem to work fine under Perl v5.36.0.

It would be nice to put a disclaimer of some sorts that informs the user about the availability of such constructs in regards to the Perl version (e.g. "//= and ||= constructs are only available in Perl v5.38.0 or later`).

[jkeenan]

Where

https://perldoc.perl.org/perlsub#Signatures

Description

Certain examples given in the Signatures section raise syntax errors when run under earlier Perl versions.

My initial reaction to this observation is, "So what?"

When we do a production release of Perl once a year, we're documenting that version of Perl, not earlier versions. There are places where we will say something like, "Up until perl-5.20, you could do X, Y and Z, but this was found to have security flaws." But, to the best of my knowledge, in a given version of Perl we do not concern ourselves with how to code in earlier, now superseded versions of Perl. If we were to try to do that, we would be creating much more work for ourselves.

My two cents.

[vaitkus]

I was in the wrong here. I did not notice that https://perldoc.perl.org/ offers version-specific documentation and that the Signature description for version 5.36.0 does not include the "//=", "||=" examples. Sorry for the noise.

[iabyn]

On Wed, Apr 17, 2024 at 05:14:00PM -0700, James E Keenan wrote: When we do a production release of Perl once a year, we're documenting *that version* of Perl, not earlier versions. There are places where we will say something like, "Up until perl-5.20, you could do X, Y and Z, but this was found to have security flaws." But, to the best of my knowledge, in a given version of Perl we do not concern ourselves with how to code in earlier, now superseded versions of Perl. If we were to try to do that, we would be creating much more work for ourselves.

I disagree. I think it is good for the main perl ref docs to include a brief note of when a significant feature was first introduced. This helps (among other things) people writing CPAN libraries to ensure that their code runs across all the versions they claim to support.

…

-- Hofstadter's Law: It always takes longer than you expect, even when you take into account Hofstadter's Law.

[Grinnz]

On Wed, Apr 17, 2024 at 05:14:00PM -0700, James E Keenan wrote: When we do a production release of Perl once a year, we're documenting that version of Perl, not earlier versions. There are places where we will say something like, "Up until perl-5.20, you could do X, Y and Z, but this was found to have security flaws." But, to the best of my knowledge, in a given version of Perl we do not concern ourselves with how to code in earlier, now superseded versions of Perl. If we were to try to do that, we would be creating much more work for ourselves.
I disagree. I think it is good for the main perl ref docs to include a brief note of when a significant feature was first introduced. This helps (among other things) people writing CPAN libraries to ensure that their code runs across all the versions they claim to support.
…
-- Hofstadter's Law: It always takes longer than you expect, even when you take into account Hofstadter's Law.

Agreed. We do this in select cases where it makes sense, and it is also helpful because the latest documentation is what is found on google (ideally) but not everyone is always on the latest Perl, and people all have different situations and experience levels with Perl.

[vaitkus]

The issue is addressed by PR #22919.