in reply to Re^4: Annotations for Perl
in thread Annotations for Perl
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.
|
|---|
| Replies are listed 'Best First'. | |
|---|---|
|
Re^6: Annotations for Perl
by hurricup (Pilgrim) on Jun 03, 2015 at 05:51 UTC |