Re^4: Annotations for Perl

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]

Isn't it too messy?

Comment on Re^4: Annotations for Perl Download Code

Replies are listed 'Best First'.
Re^5: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 23:56 UTC
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.	[reply] [d/l] [select]
Re^6: Annotations for Perl by hurricup (Pilgrim) on Jun 03, 2015 at 05:51 UTC
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.	[reply]
Re^5: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 22:21 UTC
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	[reply]