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. :-)