Re^2: Annotations for Perl

Replies are listed 'Best First'.
Re^3: Annotations for Perl by Anonymous Monk on Jun 02, 2015 at 16:54 UTC
POD's `=for` might help there, e.g. `=for ide @Returns Foo::Bar` [download] AFAIK POD parsers will ignore that if they don't recognize "ide", but your parser could pull those out.	[reply] [d/l] [select]
Re^4: Annotations for Perl by hurricup (Pilgrim) on Jun 02, 2015 at 17:31 UTC
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?	[reply] [d/l]
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
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]