Documentation on $obj->foo::bar(…) missing from 5.16 perlobj

[p5pRT]

Migrated from rt.perl.org#116945 (status was 'resolved')

Searchable as RT116945$

[p5pRT]

From jules@jellybean.co.uk

Hi,

The documentation for the particular form of method invocation where you specify a package name to begin the dispatch at​:

$obj->foo​::bar(�.)

was present in perlobj(1) up until 5.14 ( see https://github.com/mirrors/perl/blob/maint-5.14/pod/perlobj.pod ) with an example

$barney->Critter​::display("Height", "Weight");

It seems that perlobj got rewritten in 5.16 branch and this part of the file has changed, completely removing all mention of that feature. I think it deserves a mention not least because there are modules on CPAN which use this style as their api. Ideally the paragraph would also mention that you can start dispatch at an arbitrary package not necessarily in the MRO of the object.

Thanks,

Jules

PS Nicholas told me to mention soup.

[p5pRT]

From @jkeenan

On Tue Feb 26 05​:47​:17 2013, jules@​jellybean.co.uk wrote​:

Hi,

The documentation for the particular form of method invocation where
you specify a package name to begin the dispatch at​:

$obj->foo​::bar(â�¦.)

was present in perlobj(1) up until 5.14 ( see
https://github.com/mirrors/perl/blob/maint-5.14/pod/perlobj.pod )
with an example

$barney->Critter​::display("Height", "Weight");

It seems that perlobj got rewritten in 5.16 branch and this part of
the file has changed, completely removing all mention of that
feature. I think it deserves a mention not least because there are
modules on CPAN which use this style as their api. Ideally the
paragraph would also mention that you can start dispatch at an
arbitrary package not necessarily in the MRO of the object.

Thanks,

Jules

PS Nicholas told me to mention soup.

Let's see if we can find out something from the committer​:

commit af36000
Author​: Dave Rolsky <autarch@​urth.org>
Date​: Thu Jul 7 11​:35​:00 2011 -0500

[p5pRT]

The RT System itself - Status changed from 'new' to 'open'

[p5pRT]

From @autarch

On Tue Feb 26 05​:47​:17 2013, jules@​jellybean.co.uk wrote​:

Hi,

The documentation for the particular form of method invocation where
you specify a package name to begin the dispatch at​:

$obj->foo​::bar(â�¦.)

was present in perlobj(1) up until 5.14 ( see
https://github.com/mirrors/perl/blob/maint-5.14/pod/perlobj.pod ) with
an example

$barney->Critter​::display("Height", "Weight");

It seems that perlobj got rewritten in 5.16 branch and this part of
the file has changed, completely removing all mention of that feature.
I think it deserves a mention not least because there are modules on
CPAN which use this style as their api. Ideally the paragraph would
also mention that you can start dispatch at an arbitrary package not
necessarily in the MRO of the object.

Removing this was an oversight on my part when I rewrote the docs. I agree 100% that this should be documented. I'd be happy to review a patch.

[p5pRT]

From @mauke

On Mon Oct 17 08​:28​:27 2016, autarch wrote​:

Removing this was an oversight on my part when I rewrote the docs. I
agree 100% that this should be documented. I'd be happy to review a
patch.

Patch attached. Comments?

[p5pRT]

From @mauke

0001-perlobj-document-Class-method-syntax-RT-116945.patch

From b282b2a135b0f5f481d57d4a6d4c120f6d1d9068 Mon Sep 17 00:00:00 2001
From: Lukas Mai <l.mai@web.de>
Date: Fri, 21 Oct 2016 16:21:43 +0200
Subject: [PATCH] perlobj: document ->Class::method syntax (RT #116945)

---
 pod/perlobj.pod | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index d16f800..fbec6a1 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -581,6 +581,31 @@ X<method>
 Perl supports several other ways to call methods besides the C<<
 $object->method() >> usage we've seen so far.
 
+=head3 Methods that Include a Package Prefix
+
+Method calls can specify an explicit package:
+
+  my $mp3 = File::MP3->new( 'Regin.mp3', $data );
+  $mp3->File::save();
+
+This starts the search for the C<save> method in the C<File> class,
+skipping any C<save> method the C<File::MP3> class may have defined. (It
+still searches C<File>'s parent classes if necessary.)
+
+While this feature is most commonly used to explicitly call methods
+inherited from an ancestor class, there is no technical restriction that
+enforces this:
+
+  my $obj = Tree->new();
+  $obj->Dog::bark();
+
+This calls the C<bark> method from class C<Dog> on an object of class
+C<Tree>, even if the two classes are completely unrelated. Use with
+care.
+
+The special case of a C<SUPER::> prefix does not refer to a real class.
+It is described under L</Inheritance> above.
+
 =head3 Method Names as Strings
 
 Perl lets you use a scalar variable containing a string as a method
-- 
2.10.0

[p5pRT]

From @tonycoz

On Fri Oct 21 07​:25​:54 2016, mauke- wrote​:

On Mon Oct 17 08​:28​:27 2016, autarch wrote​:

Removing this was an oversight on my part when I rewrote the docs. I
agree 100% that this should be documented. I'd be happy to review a
patch.

Patch attached. Comments?

That looks good to me, I'll wait a couple of days to see if Dave
has a comment before applying it.

Tony

[p5pRT]

From @autarch

On Mon Oct 31 15​:33​:55 2016, tonyc wrote​:

On Fri Oct 21 07​:25​:54 2016, mauke- wrote​:

On Mon Oct 17 08​:28​:27 2016, autarch wrote​:

Removing this was an oversight on my part when I rewrote the docs. I
agree 100% that this should be documented. I'd be happy to review a
patch.

Patch attached. Comments?

That looks good to me, I'll wait a couple of days to see if Dave
has a comment before applying it.

I've been ridiculously busy recently but I did want to review this. (I really really really wish we used something like github, it'd make this so much easier.)

I think I can get to it this weekend. If I don't, please feel free to apply it as is. I can always submit a follow-up patch.

[p5pRT]

From @autarch

An edited version of the patch is in http​://perl5.git.perl.org/perl.git/shortlog/refs/heads/autarch/oo-doc-ref-patch and I've asked p5p to review.

[p5pRT]

From @tonycoz

On Tue, 01 Nov 2016 12​:38​:35 -0700, autarch wrote​:

An edited version of the patch is in
http​://perl5.git.perl.org/perl.git/shortlog/refs/heads/autarch/oo-doc-
ref-patch and I've asked p5p to review.

I don't see such a branch.

Was it committed to blead as 3556f4b and 3556f4b ?

If so this ticket can be closed.

Tony

[p5pRT]

From @autarch

On Tue, 15 Nov 2016 18​:33​:38 -0800, tonyc wrote​:

On Tue, 01 Nov 2016 12​:38​:35 -0700, autarch wrote​:

An edited version of the patch is in
http​://perl5.git.perl.org/perl.git/shortlog/refs/heads/autarch/oo-
doc-
ref-patch and I've asked p5p to review.

I don't see such a branch.

Was it committed to blead as 3556f4b
and 3556f4b ?

Yes, this is in blead. I don't have perms to mark the ticket resolved though.

[p5pRT]

@tonycoz - Status changed from 'open' to 'pending release'

[p5pRT]

From @khwilliamson

Thank you for filing this report. You have helped make Perl better.

With the release today of Perl 5.26.0, this and 210 other issues have been
resolved.

Perl 5.26.0 may be downloaded via​:
https://metacpan.org/release/XSAWYERX/perl-5.26.0

If you find that the problem persists, feel free to reopen this ticket.

[p5pRT]

@khwilliamson - Status changed from 'pending release' to 'resolved'