Interesting idea. But there is a one thing which is bad for this case - excessive new lines. As far as i remember, let's say pod statement should have \n\n as it's end. So our annotation should be like:

=for ide

@returns Foo::Bar

=cut

sub somefunc(){...}
[download]

See perlpod: =for actually shouldn't have a blank line after it, and according to the docs its contents can be on the same line, so something like =for ide @Returns Foo::Bar should be fine. So if the function already has a POD section preceding it, you'd only be adding one or two lines plus a blank line. I don't think that's too messy.

On a more philosophical note, I don't really see the point of trying to make the documentation section before a function (be it JavaDoc or Doxygen or POD) "compact": if someone has already made the choice to write a good piece of documentation for each function, that's going to take some space, so a couple extra lines to document return values and such don't hurt.

That doesn't cover the case you mentioned earlier of someone just wanting to throw a quick one-line annotation before a function... but for those cases maybe the #@Returns ... style from your OP is fine.

Yes, you may put text with any pod opener, but you need close tag and newline after it and i belive it's pretty big overhead for one annotation. But thanks for your comments, they've been very useful.

Isn't it too messy?

Nope. There is no reason pod has to go in the source code, it can go in its own .pod file.

But then again magic comments can be added to the .pod file as well.

A separate file for the distractions makes sense