Bug#929712: perlfunc: "do EXPR" documentation issues concerning error checking

[Vincent Lefevre]

Package: perl-doc
Version: 5.28.1-6
Severity: normal

In the perlfunc(1) man page (or with "perldoc -f do"):

  If "do" can read the file but cannot compile it, it returns "undef"
  and sets an error message in $@.  If "do" cannot read the file, it
  returns undef and sets $! to the error.  Always check $@ first, as
  compilation could fail in a way that also sets $!.  If the file is
  successfully compiled, "do" returns the value of the last
  expression evaluated.

with the example

    unless ($return = do $file) {
        warn "couldn't parse $file: $@" if $@;
        warn "couldn't do $file: $!"    unless defined $return;
        warn "couldn't run $file"       unless $return;
    }

The last warn

        warn "couldn't run $file"       unless $return;

does not match the documentation about errors, which does not say
anything in the case where $return is defined but not regarded as
true.

Moreover, what happens if the file can be run, but the last
expression evaluated returned undef?

And what if there are no expressions evaluated (e.g., empty file)?

-- System Information:
Debian Release: 10.0
  APT prefers unstable-debug
  APT policy: (500, 'unstable-debug'), (500, 'stable-updates'), (500, 'unstable'), (500, 'testing'), (500, 'stable'), (1, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.19.0-5-amd64 (SMP w/12 CPU cores)
Kernel taint flags: TAINT_PROPRIETARY_MODULE, TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=POSIX, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=POSIX (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages perl-doc depends on:
ii  perl  5.28.1-6

perl-doc recommends no packages.

Versions of packages perl-doc suggests:
ii  groff-base            1.22.4-3
ii  man-db [man-browser]  2.8.5-2

-- no debconf information