Bug#679900: package description copied from manual page

[Justin B Rye]

Martin Eberhard Schauer wrote:
> Dear Perl Maintainers,
> translating the description (1) I wondered whether it is too technical.
> Actually the text appears to be copied from the manual page (2).
> 
>    Description: Perl module containing stack trace and stack trace frame objects

(I suppose we could complain that "Perl module" seems redundant for a
package named "lib*-perl", but it's probably not worth trying to find
anything better.)

>     The Devel::StackTrace module contains two classes, Devel::StackTrace
>     and Devel::StackTraceFrame.  The goal of this object is to encapsulate
>     the information that can found through using the caller() function, as
>     well as providing a simple interface to this data.
> 
> I'm not comfortable with the wording here. I'm not a Perl programmer yet and I
> believe that a module provides code for a class that becomes instantiated in
> an object.

Or to look at it another way, a Perl "class" is a Perl package that
provides subroutines ("methods") for handling data references of a
special kind ("objects").  So... I'm not sure what the issue is here.
I'm not keen on the way it jumps to "this object" - is that it?

>     .
>     The Devel::StackTrace object contains a set of Devel::StackTraceFrame
>     objects, one for each level of the stack.  The frames contain all the
>     data available from caller() as of Perl 5.6.0 though this module still
>     works with 5.00503.
> 
> These are quite old Perl versions. They are not mentioned by upstream (2) any
> more.

Indeed, Perl 5.6 came out in 2000, so yes, this needs an update.

>     .
>     This code was created to support the Exception::Class::Base class
>     (part of Exception::Class) but may be useful in other contexts.
> 
> I doubt that this is information suitable for the clueless person considering
> whether to install this module.

Well, it may not be a -dev package, but it is a libdevel-*, so they'd
be getting the right impression.  The main reason this package would
be installed is because it's pulled in automatically as a runtime
dependency of various things like request-tracker4.
 
> Please consider this shortened version:
> 
>    Description: Perl module providing stack trace facilities
>     The Devel::StackTrace module provides two classes, Devel::StackTrace
>     and Devel::StackTraceFrame.
>     .
>     The Devel::StackTrace object encapsulates the information that can be
>     obtained by using the caller() function, as well as providing a simple
>     interface to this data.
>     .
>     The Devel::StackTrace object contains a set of Devel::StackTraceFrame
>     objects, one for each level of the stack.  The frames contain all the
>     data available from caller().

The problem here is that after it says there are two of them, D::ST
and D::STF, it's confusing that both of the following paragraphs
appear to be describing D::ST - it's not clear that the second
paragraph is effectively defining D::STF.

I may be squeezing too far, but would the following still be an
accurate summary?

      The Devel::StackTrace module provides two classes.
      .
      Devel::StackTrace objects provide a simple interface to the data
      available from caller(), encapsulating the information from a set of
      Devel::StackTraceFrame objects.
      .
      Devel::StackTraceFrame objects each contain the caller data for one
      level of the stack.

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package