The doc looks clear enough to me, but maybe it's because I already knew splice's behaviour. Were you expecting something else instead? Like zero being equivalent to an omitted length, where everything until the end is removed?

The unshift example does show explicitly that a length of 0 removes nothing, but it requires understanding unshift, which is not beginner friendly. Maybe the examples list could include an insertion and removal, which is would be more helpful than things that can be done using more specific functions.

Edit: I realized that while the case where LENGTH is omitted or negative are explicitly described, the case where it's positive is only implied because of the name of the parameter. So, rather than the specific case of zero, "If LENGTH is positive (or zero), LENGTH elements are removed".

As usual when I post, what's obvious to me doesn't get written down. :/

I should have added:

Here's my use case:

splice(@array, 7, 0, qw(stuff I want to insert));
[download]

So if I want to insert something, but not remove anything, I need a length of zero.

-QM
--
Quantum Mechanics: The dreams stuff is made of

QM:

The documentation seems clear enough to me, but I can see where a little extra info could help. I think I'd suggest adding "If LENGTH is zero, nothing is removed. " just before the "If LENGTH is omitted" bit. It might also be helpful to rearrange the examples under "The following equivalences hold" bit with a couple comments:

# delete nothing but add to end or beginning of array:
push @a,$x,$y     splice(@a,@a,0,$x,$y)
unshift @a,$x,$y  splice(@a,0,0,$x,$y)

# Remove first or last item from array:
$t=pop @a         $t=splice(@a,-1)
$t=shift @a       $t=splice(@a,0,1)

# Replace item in middle of array
$a[$i]=$y         splice(@a,$i,1,$y)
[download]

...roboticus

When your only tool is a hammer, all problems look like your thumb.

if LENGTH is 3, three elements are removed. if LENGTH is 2, two elements are removed. if LENGTH is 1, one element is removed. if LENGTH is 0, ...