I think an examples section is a good idea, but I wouldn't want a full working example in the synopsis. The data structures it's working on tend to be large on the page, and I want to keep the synopsis short. For example, here's the shortest of the functional test cases I have so far:
{
name => 'two keys',
group_by => ['key1', 'key2'],
group_how => {
count => 'count',
},
input => [
{
key1 => 'a',
key2 => 'a',
},
{
key1 => 'a',
key2 => 'a',
},
{
key1 => 'a',
key2 => 'a',
},
{
key1 => 'a',
key2 => 'b',
},
{
key1 => 'a',
key2 => 'b',
},
],
expected => [
{
key1 => 'a',
key2 => 'a',
count => 3,
},
{
key1 => 'a',
key2 => 'b',
count => 2,
},
],
},
