(tye)Re: Inline POD vs. EOF POD

[tye]

Inline POD certainly restricts the possible format of your documentation. Win32::TieRegistry's documentation would suck by comparison if I tried to use inline POD for it.

The advantage of inline POD is that you can keep the documentation of the interface close to the definition of the interface. The problems with that are that 1) good POD should contain a lot more than just the documentation of the interface and 2) Perl doesn't let you define an interface other than via its implementation.

So inline POD forces the co-mingling of the implementation and lots of non-interface documentation (like examples, explanations, etc.). This can easily make the implementation fragmented and harder to understand/maintain and make the documentation fragmented and harder to understand/maintain.

Now, if Perl offered interface declarations (like subroutine prototypes in many other languages), then I'd likely co-mingle those into the POD.

But I mostly don't use co-mingled POD because I think it leads to pretty ugly documentation. I like to control the flow of the documentation in hopes of making it easy to understand and also control the flow of the code for the same reason. These goals usually don't lead to the code being in the same order as the POD so I usually don't co-mingle them.

Update: Yes, Perl subroutine declarations, especially of OO methods, only define a name and so are pretty useless. If Perl had "more traditional" subroutine declarations, than changing the interface w/o updating the documentation (where the declaration is co-mingled) should produce an error about mismatched prototypes in order to remind you to update the documentation.

        - tye (but my friends call me "Tye")