in the Java world, there are magic libraries that people never really have to know about ... But with Perl, we generally see more of the guts of packages

If you're talking about Class::DBI, then I have to disagree. The only thing you have to do is define the table structure. It handles all the SQL behind the scenes, as well as the creation of classes. And if you don't even want to define the table structure, there's Class::DBI::Loader, which reads it directly from the database. I'm not sure how much more magical you can get.

If you're talking about Perl and Java in general, then, again, I can't agree. My experience says the opposite. I find Perl modules do more "magic" than Java libraries, on the whole. Perhaps you could convince me otherwise with some specific examples, but I digress.

It says it creates the accessors/mutators, but it's not clear whether they're just get/set methods or (as it seems to imply) that it creates lvalue methods

It's pretty clear to me that they're the argument-taking variety of get/set methods, rather than lvalues. Here's an example from the SYNOPSIS:

    my $cd = $artist->add_to_cds({ 
        cdid   => 1,
        title  => 'October',
        year   => 1980,
    });

    # Oops, got it wrong.
    $cd->year(1981);
    $cd->update;
[download]

Notice the call to year on the $cd object.

Well, maybe it's the way packages are documented, or maybe because Perl is an organic effort, or maybe the official Java API documentation feels easier on my eyes. Or perhaps I feel this way because I have more experience with Java packages than Perl modules.

In the example above, for instance, there is no method specifically declared "add_to_cds()" in package Artist. I wondered if someone wrote a package so ingenious that just relating Artists to CDs in a certain way would automatically generate methods like these; with Perl, you never know, I mean I don't see why it can't be done. But of course I doubt that this is the case -- but I knew right then that there was stuff implied in the examples that wouldn't be immediately obvious to me. I felt like I was left dangling a bit.

And then I had to make the leap from seeing a method I know nothing about (add_to_cds()) do something that's not documented (it actually creates and returns a new CD). My assumptions are probably right (rule of least surprise meets DWIM and TMTOWTDI, right?), but I'm not completely positive -- the DWIM to TMTOWTDI ratio is low. Of course, a few lines later the example code shows that those assumptions are probably 100% correct, because of the reference to $cd passed back, and later manipulated. Nevertheless, I had to decipher the documentation. In other words, I needed documentation on the documentation, I needed more commentary. Actually, in-line comments would have been perfectly fine.

Well, maybe it's the way packages are documented, or maybe because Perl is an organic effort, or maybe the official Java API documentation feels easier on my eyes.

I am a bit surprised by this. I thought you were talking about the way Perl modules work. Earlier you said that Java has "magic libraries" that people "never really have to know about," compared to Perl, where "we generally see more of the guts of packages." This led me to believe you were talking about the way the libraries and modules actually function, but I could easily have misunderstood your point.

Instead, are you only talking about the docs? If so, I would probably agree. The documentation for most of the standard Java API is pretty good. There does tend to be a "can't see the forest for the trees" type of mentality, but the trees are usually well documented enough to infer the forest.

With Perl, on the other hand, it's generally the other way around. The forest (as revealed in a SYNOPSIS) is usually pretty nicely described, but the trees are often barely touched on. [Hopefully you still know what the heck I'm talking about, despite this terribly strained analogy.]

Of course, since I'm talking in generalities, there will be counter-examples on both sides, and perhaps I'm just dead wrong. I'm simply describing things the way I have experienced them.

there is no method specifically declared "add_to_cds()" in package Artist ... I knew right then that there was stuff implied in the examples that wouldn't be immediately obvious to me. I felt like I was left dangling a bit.

I can't agree with your assessment of Class::DBI's docs here. In fact, it appears to be one of the counter-examples that I mentioned earlier. It sounds to me like you only read the SYPOSIS, then stopped. The SYNOPSIS is only meant to be a brief introduction to what the module has to offer. If you search for "add_to", you will find that this behavior is clearly explained in the following:

In addition it creates another method which allows a new associated object to be constructed, taking care of the linking automatically. This method is the same as the accessor method with "add_to_" prepended.

There's not much mystery here. I think this DWIM about as much as possible.

Of course, a few lines later the example code shows that those assumptions are probably 100% correct ... I needed documentation on the documentation, I needed more commentary.

I think what you really needed was to read more of the documentation that was there. These things are explained in excruciating detail further down in the docs, and all it takes is a quick search to find them. Perhaps you didn't realize what the SYNOPSIS was all about, but now you should have no excuse. :-)