The Best Practices suggest creating a template for block comments that are suitable for your team. On the whole the reasons given in the book are good ones and it sounds like a great idea, but I find it harder to implement in practice.
One of the things I think comes up most is that teams pick a too-verbose comment block – the first example in the book is a good example of that – and wind up writing a bunch of boilerplate comments that are longer than simple functions themselves. I don’t find this a good use of engineer time, nor does it really help when functions are straightforward.
This is even more true when using helpers to write functions for you, such as Moose accessors. I admit, I do write POD for them as if they were functions, so they show in the docs as interfaces, but I don’t stop and define every detail of how they might be used. I define what they are for, not all the details of how they’re called. The calling convention for simple functions and well-known patterns is simple. For example, I think that duplicating that this is an accessor that returns the old value and optionally sets a new one in every accessor you write adds little value.