| Subject: | API and documentation contradict each other; undocumented behaviour changes after the 1.x->2.x transition |
Hi,
I am a member of the Debian pkg-perl group - We are the maintainers for
Compress::Zlib in the Debian GNU/Linux distribution.
Magnus Holmgren noticed that, after the 2.x transition, the
documentation contradicts the actual API. Some behaviour as changed
(which is understandable after a major transition), but the
documentation still points what was true before.
I'm reproducing his bug report here - For further correspondence, don't
hesitate to mail our BTS directly (440943@bugs.debian.org), or check the
status via the web interface
(http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=440943).
Package: libcompress-zlib-perl
Version: 2.005-3
Severity: important
Tags: upstream
Compress::Zlib(3pm):
$gz->gzclose
Closes the compressed file. Any pending data is flushed to
the file before it is closed.
Returns 1 on success, 0 on failure.
The actual code:
sub Compress::Zlib::gzFile::gzclose
{
my $self = shift ;
my $gz = $self->[0] ;
my $status = $gz->close() ;
_save_gzerr($gz);
return ! $status ;
}
IO::Compress::Gzip(3pm):
close
$z->close() ;
close $z ;
Returns true on success, otherwise 0.
Compress::Zlib::gzFile::gzclose inverts the result from the underlying
call, thus it returns 0 on success, 1 on failure. Contrary to the
documentation.
On the other hand, Compress::Zlib::gzFile::gzflush() does indeed
return 1 on success and 0 on failure, which is the opposite of what
versions before 2.0 did, thus potentially breaking many applications.
Neither README nor changelog documents the change.
I haven't checked all subroutines, but gzwrite() and gzread() seem to
work the same.
--
Magnus Holmgren holmgren@lysator.liu.se