It looks useful, but after glancing through your module I still don't know how to use it. I don't know how SQL GROUP BY works, and you say that's assumed, so I can't really complain. :-)

However, I think it's a good idea to have a full example in the synopsis. With full example I mean that it should compile and run, and some sensible output/results should also be included when applicable. Usually I get a good idea of what the code does and how I can use it by just looking at the input/transform/output triplet.

This is particularly important for this kind of module that transforms one data structure to another. You show the transform, but you don't show what goes in and what comes out. What is @AOH, and how does "key1" and "field1" relate to @AOH?

While the synopsis should just highlight what the module does, I often appreciate one or two slightly more elaborate (and possibly realistic) examples of the code at the end (under e.g. =head1 EXAMPLES).

Returning to including output in the synopsis; I often use __END__ to separate the code from the output (see examples at CPAN). I've written a test module for that which I've pondered for release. Basically, the synopsis becomes a part of the test suite. This makes sure that there are no typos in the synopsis and that it is up to date. If anyone shows any interest I might write up an RFC.

lodin