[VPM] RFC: multi-package module best practices

[Darren Duncan]

P.S. I also sent this email to modules at cpan.org, but I am also 
sending it to you in case you have some good insights to share too.
----------------------------

Hello.

I have a question regarding "best practice" details concerning a 
module which declares multiple packages/classes inside that should be 
visible to the public.

Say, for example, I have a single object-oriented Perl 5 module named 
"Foo.pm", and it contains these 3 package declarations inside: "Foo", 
"Foo::Bar", "Foo::Baz".  The "NAME" POD inside only gives a one-liner 
for "Foo" as that is the namesake package, though it is mainly 
"Foo::Bar" and "Foo::Baz" which users of the module actually make 
instances of, pass around, store data in, test for by name using 
"UNIVERSAL::isa", and so on.  (They issue just "use Foo" before using 
any one of them to compile the whole set.)

In this example, users of the Foo module are treating Foo::Bar and 
Foo::Baz as distinct entities to use, but those two classes are 
implemented in a single module file for convenience as they are 
normally used together, and the POD for the Foo module says they are 
components of Foo and documents a separate method list for each.

Now some of the questions (answer just the ones you want):

1. Since the two classes in the example are always used together, is 
it reasonable to have them in a single module with unified 
documentation (much of which describes them together), or is it 
better to have Foo::Bar and Foo::Baz as separate physical modules 
where the file names match the package names (eg: lib/Foo/Bar.pm and 
lib/Foo/Baz.pm).  Which is easier to use or understand?

2. Since people are meant to use each package directly, would it be 
better to have normal-looking names like Foo::Bar, or would it be 
better to have a different looking name such as Foo::_::Bar which 
makes the name stand out as being declared inside a module with a 
different name?  What would be best practice or easier to use?  (Note 
that I would still use the "::_" for any additional inner classes 
that are meant to be private and only used by the public-visible 
ones, such as Foo::_::Shared, to avoid possible namespace collisions 
later.)

3. Concerning CPAN's tracking of module ownership and registration: 
Is module ownership tracked and attributed by file/path name or by 
the name of the package declaration inside or by the NAME POD?

4. Related to #3, if I were to upload said module Foo.pm to CPAN, 
would the system register me as the maintainer/owner of Foo::Bar and 
Foo::Baz in addition to Foo?  I want to avoid a situation where, for 
example, someone later uploads their own extension module named 
Foo::Bar in a file named "lib/Foo/Bar.pm" and then get ownership to 
Foo::Bar.

Now for a bit of context:

1. For all intents and purposes, I have 3 actual modules on CPAN now 
which are organized in the multiple-package fashion that I described 
above:
	Rosetta - presently contains [*::Interface, *::Engine]
	SQL::SyntaxModel - [*::_::Container, *::_::Node]
	Locale::KeyedText - [*::_::Message, *::_::Translator]
For the first one, the inner classes were visible to the PAUSE 
indexer.  For the latter two, the inner package declarations were 
mangled slightly (split into 2 lines each) to not be visible to the 
PAUSE indexer.

2. Some other modules, such as DBI, also have multiple related 
package declarations in them; however, in the case of DBI, users 
never do the equivalent of "new" except with one package; other 
package objects are created in the context of an existing object.  My 
situation is different than DBI, though, in that all package types 
are instantiated as objects in a stateless context.

3. I want to standardize my modules so all of the public inner 
classes either have the "::_" in their names or they all do not.  I'm 
inclined to go "not", but wanted to get second opinions first.

That's all for my questions at the moment.

Thank you in advance for any advice or opinions you can give me.

Have a good day. -- Darren Duncan