Once again, I failed to grok the vim docs, but I finally got this working. If you have an editor which implements folding, you probably love having annoying things folding out of the way. I find POD annoying. Almost all of my modules are written with inline POD because I believe it's very important for the documentation to be next to the code, but if you've worked on a codebase for any length of time, that POD quickly becomes annoying. The following will fold your POD out of the way without folding other bits:
let perl_fold=1 let perl_nofold_packages=1 let perl_nofold_subs=1
I expect that's rather self-explantory. See :help fold for more folding options. (quick tip: 'zd' on the fold line will unfold the POD).
To learn more about vim's syntax options for Perl: :help ft-perl-syntax.
Folding in vim will usually show the first line of text folded (you can override this). Because the first line of text in our POD is usually a signature, we get this:
+-- 8 lines: =head2 resultset_with_request_params($c, $rs) : $rs------------
In short, every function comes with a quick synopsis with this. Very, very handy.
"Almost all of my modules are written with inline POD because I believe it's very important for the documentation to be next to the code, but if you've worked on a codebase for any length of time, that POD quickly becomes annoying".
You like to have the Pod by the code but it is annoying. So this fixes it for you by making it not annoying.
What about the next person who reads your code and doesn't have a Vim Pod folding macro. They are going to find it annoying, right?
Inline Pod *is* annoying. It make code difficult to read, especially if it contains code snippets. But you could avoid the annoyance by putting the Pod after the __END__. Then no-one will have to make their editor, or their brain, jump through hoops.
Putting the documentation near the code is no guarantee that it will get updated when the code does.
John.
--
Re: Vim: Folding POD Out Of the Way
Ovid on 2009-02-24T12:02:40
Putting the documentation near the code is no guarantee that it will get updated when the code does.
Agreed, but putting documentation after the __END__ is pretty much a guarantee that it will not get updated when the code does. (That's been my experience; your mileage may vary.)
Re: Vim: Folding POD Out Of the Way
jmcnamara on 2009-02-24T14:10:13
Either way it comes down to the diligence of the maintenance programmer so I don't see the advantage.
What I do see is the disadvantage. The blocks of Pod that you say "quickly becomes annoying".
If you step back from this don't you get one of those smells that you like to look out for. What it looks like to me is that a method of documenting a module is "annoying" and that the solution is to change the behaviour of the tool for viewing the code. That doesn't look like a good solution to me since it only works for one user.
John.
--Re: Vim: Folding POD Out Of the Way
Ovid on 2009-02-24T14:25:55
I can see that point. I guess the reason I switched to inline POD is because it makes writing documentation very easy for me. Of course, folding the POD also becomes useful when I'm working on someone else's code. I can't dictate to them how to write their POD, so I work around that.
Re: Vim: Folding POD Out Of the Way
mpeters on 2009-02-24T14:45:29
What I do see is the disadvantage. The blocks of Pod that you say "quickly becomes annoying".
He fixed one big annoyance (documentation far removed from the code such that it doesn't get updated when the code does) which causes another smaller annoyance (lots of small POD blocks scattered in your code).
Trading big problems for small problems is what we do as programmers. How is this any different?
And in any case, he's solved the small problem (at least for his tastes, which is all an editor can really do), so why the criticism?
I'm also a big fan of inline POD. Not only does it keep related things together, but it's much easier to keep the code and docs in sync that way. That one fact right there is worth it to me, even with some minor annoyances.
But I've never been a big fan of code folding (again, just a preference) so I've altered my vim color scheme to put POD into a more muted color pallete than the code. So when looking at it, my eyes just don't see the POD until I focus on it.
You can see an example of my color scheme here:
http://www2.plusthree.com/user/mpeters/vim/mpeters_vim_color.png
Almost all of my modules are written with inline POD because I believe it’s very important for the documentation to be next to the code, but if you’ve worked on a codebase for any length of time, that POD quickly becomes annoying. The following will fold your POD out of the way
… so what you’re saying is it’s so important for POD to be next to the code that you want a way to make it go away so that it will be less annoying that it’s there. I see.
Personally I prefer POD at the end of the file, whereupon I can use this other nice feature of better editors, namely splitting a window, so I can see both the code and the docs at the same time, at my leisure. That works much better for me in a lot of ways.
Re:Wait...
Burak on 2009-02-25T10:29:18
I also prefer the it at the end. I think inline Pod is annoying and it also creates an overhead in the parser. We had mixed Pod in my previous $job. Some were inline some were after the __END__ I wish adding them after __END__ was in the coding standards
:) But, anyway there are far more annoying things in the actual code of other people other than Pod...
