Mailing List Archive: Perl: porters

[perl #114280] Carp's longmess() and shortmess() should be documented

Index | Next | Previous | View Threaded

perlbug-followup at perl

Jul 26, 2012, 4:12 PM

Post #1 of 4 (100 views)
Permalink

[perl #114280] Carp's longmess() and shortmess() should be documented

On Thu Jul 26 07:49:59 2012, srezic [at] cpan wrote:
>
> This is a bug report for perl from srezic [at] cpan,
> generated with the help of perlbug 1.39 running under perl 5.16.0.
>
>
> -----------------------------------------------------------------
> The documentation for these functions were largely removed in commit
> d735c2efe0b08b05adfb893625476bf4480a2ece (there's still one place
> mentioning "longmess" without any further explanation).
>
> In the discussion in
> http://www.nntp.perl.org/group/perl.perl5.porters/2006/10/msg117394.html
> the removal was explained:
>
> | - Removed documentation of shortmess and longmess. Unfortunately
> | longmess doesn't do anything particularly reasonable, and it can't
> be
> | made to do so because of backwards compatibility with code that
> | depended on the old behaviour.
>
> However, longmess() and shortmess() are still exported.

Confirmed. Any identifier which is exportable must be documented.

> And there's a
> lot of code which is still using longmess(). Just try "git grep
> Carp::longmess" in perl's source code, and I assume that many CPAN
> modules are also using longmess().

See attachment for results of: ack -l 'Carp::(long|short)mess' *

> So for me it looks like longmess()
> *is* doing something reasonable.
>
> My suggestion is to restore the documentation, or to at least mention
> the functions, and explain the shortcomings if there are any.
>

Agreed.

---
via perlbug: queue: perl5 status: new
https://rt.perl.org:443/rt3/Ticket/Display.html?id=114280

Attachments:

114280_longmess.txt (0.79 KB)

perlbug-followup at perl

Jul 26, 2012, 6:38 PM

Post #2 of 4 (85 views)
Permalink

[perl #114280] Carp's longmess() and shortmess() should be documented [In reply to]

On Thu Jul 26 16:12:11 2012, jkeenan wrote:
> On Thu Jul 26 07:49:59 2012, srezic [at] cpan wrote:
> >
> > This is a bug report for perl from srezic [at] cpan,
> > generated with the help of perlbug 1.39 running under perl 5.16.0.
> >
> >
> > -----------------------------------------------------------------
> > The documentation for these functions were largely removed in commit
> > d735c2efe0b08b05adfb893625476bf4480a2ece (there's still one place
> > mentioning "longmess" without any further explanation).
> >
[snip]
> >
> > My suggestion is to restore the documentation, or to at least mention
> > the functions, and explain the shortcomings if there are any.
> >
>
> Agreed.
>

Patch attached; please review.

Thank you very much.
Jim Keenan

---
via perlbug: queue: perl5 status: open
https://rt.perl.org:443/rt3/Ticket/Display.html?id=114280

Attachments:

0001-Document-exportable-subroutines-longmess-and-shortme.patch (2.52 KB)

perl.p5p at rjbs

Jul 26, 2012, 7:31 PM

Post #3 of 4 (86 views)
Permalink

Re: [perl #114280] Carp's longmess() and shortmess() should be documented [In reply to]

* James E Keenan via RT <perlbug-followup [at] perl> [2012-07-26T19:12:12]
> >
> > However, longmess() and shortmess() are still exported.
>
> Confirmed. Any identifier which is exportable must be documented.

You know, I have been using those for ages, and one day I realized they weren't
documented. What a relief to learn that once upon a time they were.

They should be, again. I'd love to know just what was so unreasonable about
them, compared to the "normal" bits of Carp, since I've got code that uses
them.

They should be documented. If they need a "but don't use these, because XYZ"
then so be it.

--
rjbs

Attachments:

signature.asc (0.48 KB)

perl.p5p at rjbs

Sep 27, 2012, 7:05 PM

Post #4 of 4 (39 views)
Permalink

Re: [perl #114280] Carp's longmess() and shortmess() should be documented [In reply to]

* James E Keenan via RT <perlbug-followup [at] perl> [2012-09-14T21:34:16]
> Is the patch I submitted on July 26 acceptable?

Looks good to me. If someone remembers what caveats need to be added, we can
add them.

--
rjbs

Attachments:

signature.asc (0.48 KB)

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads