Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Ovid (2709)

Ovid
  (email not shown publicly)
http://publius-ovidius.livejournal.com/
AOL IM: ovidperl (Add Buddy, Send Message)

Stuff with the Perl Foundation. A couple of patches in the Perl core. A few CPAN modules. That about sums it up.

Journal of Ovid (2709)

Tuesday February 24, 2009
05:19 AM

Vim: Folding POD Out Of the Way

[ #38543 ]

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.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • "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 di

    • 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.)

      • 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 work

        • 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.

        • 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:
    h [plusthree.com]

  • 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 P

    • 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...