Bug #87108 for Moo: Moo::Object should be considered part of Moo's public API.

Sat Jul 20 13:29:15 2013 perl [...] toby.ink - Ticket created

Subject:

Moo::Object should be considered part of Moo's public API.

By which, I mean its purpose and its methods should be documented. (I'm happy to do the actual documentation if others agree with this idea in principle.)

Mon Jul 22 01:39:16 2013 ether [...] cpan.org - Correspondence added

Subject:	Re: [rt.cpan.org #87108] Moo::Object should be considered part of Moo's public API.
Date:	Sun, 21 Jul 2013 22:38:58 -0700
To:	Toby Inkster via RT <bug-Moo [...] rt.cpan.org>
From:	Karen Etheridge <ether [...] cpan.org>

On Sat, Jul 20, 2013 at 01:29:16PM -0400, Toby Inkster via RT wrote: Show quoted text

> Subject: Moo::Object should be considered part of Moo's public API. > By which, I mean its purpose and its methods should be documented.

Why should they be public/documented? If they are public, users might hook against them directly. Why would this be a good thing?

Mon Jul 22 01:39:17 2013 The RT System itself - Status changed from 'new' to 'open'

Mon Jul 22 08:10:28 2013 haarg [...] haarg.org - Correspondence added

Moo::Object shouldn't be used directly by anyone, and the things it provides are already documented in the main Moo docs. I don't see why we'd want to make it part of the public API.

Mon Jul 22 09:57:48 2013 perl [...] toby.ink - Correspondence added

On 2013-07-22T13:10:28+01:00, haarg wrote: Show quoted text

> Moo::Object shouldn't be used directly by anyone

Not directly, but it's used indirectly (via subclassing) by almost anyone who uses Moo. It's also useful as an empty class for: my $class = 'Moo::Role'->create_class_with_roles('Moo::Object, @roles); Show quoted text

> and the things it > provides are already documented in the main Moo docs.

There are methods it provides which are not documented: meta, BUILDALL, DEMOLISHALL. People creating subclasses of Moo::Object (i.e. almost anyone who uses Moo) need to be aware of these methods, even if only to avoid accidentally overriding them.

Tue Aug 20 23:15:01 2013 haarg [...] haarg.org - Correspondence added

On Mon Jul 22 09:57:48 2013, TOBYINK wrote: Show quoted text

> On 2013-07-22T13:10:28+01:00, haarg wrote:

> > Moo::Object shouldn't be used directly by anyone

> > Not directly, but it's used indirectly (via subclassing) by almost > anyone who uses Moo. > > It's also useful as an empty class for: > > my $class = 'Moo::Role'->create_class_with_roles('Moo::Object, > @roles); >

> > and the things it > > provides are already documented in the main Moo docs.

> > There are methods it provides which are not documented: meta, > BUILDALL, DEMOLISHALL. People creating subclasses of Moo::Object (i.e. > almost anyone who uses Moo) need to be aware of these methods, even if > only to avoid accidentally overriding them.

My preference would be to document BUILDALL/DEMOLISHALL in the Moo docs, and not have Moo::Object as a public API. And anyone trying to use it directly via create_class_with_roles gets to keep both halves.

Tue Aug 27 13:24:34 2013 haarg [...] haarg.org - Correspondence added

Reconsidering things, I don't think it's a good idea to document these. This matches up with Moose, which explicitly removed the docs for these subs. It will only add confusion to list them as "they exist, but you shouldn't use them".

Tue Aug 27 13:24:36 2013 haarg [...] haarg.org - Status changed from 'open' to 'rejected'