I usually place synopsis at the beginning of the file, function descriptions right above functions and the rest after the __END__. For me it's convenient and I don't find this ugly.

If you doesn't like this style and want to place all POD after the __END__ it shouldn't be a problem. Most of editors (though I actually familiar only with Vim ;) allows to split file and see its different parts simultaneously. Also folding may be helpful if you don't want to see long functions' descriptions.

Approach with auto-copying looks somehow strange for me. Do you suggest to move function descriptions to the end of the file before closing and move them back just after opening? It doesn't make sense. If you do not plan to move descriptions back, then why not to place them in the end of the file since beginning?

>> Approach with auto-copying looks somehow strange for me. Do you suggest to move function descriptions to the end of the file before closing and move them back just after opening? It doesn't make sense. If you do not plan to move descriptions back, then why not to place them in the end of the file since beginning?

No, rather that one can run an autogenerate function which would produce "=item somefunctionname (arg1, arg2) in the correct place (METHODS) in the __END__ POD section. There is no need to move anything back. The problem I'm trying to solve is to have a simple editing trick that helps me keep the now two areas synchronized (METHOD and actual functions). A split screen helps, but is no longer helpful when you have a ton of functions. For example, try finding the new one that has no documentation...again, you must scroll through things. This is one of the benefits of colocating function and documentation, because it's obvious when you haven't documented.

However, when you have a lot of documentation intermixed with the code, it interrupts your looking at the logic. Comments do nothing to enhance the running of the code. While they help you to understand the code, there are "in code" comments and comments that are safely left elsewhere. Putting the bulk of comments with the code just makes it harder to debug.

Regardless of which editor you use and which approach, you incur some amount of busiwork while editing when you have lots of inline comments. Folding requires clicking on +/-. Searching requires jumping over false hits in the docs.

Again I find _most_ of the long documentation that I write is for other people, and I only need the briefest of reminders (perhaps _no_ docs) in with the functions. If a comment _is_ amongst the code, I've put it there to explain something obvious, or to help split up the logic of a big function (e.g. describe what happens in this stage). But these are _internal_ comments (about the implementation, for the maintainer), not _external_ comments (for the user of the library).

Also I wasn't thinking of making this an editor script (emacs, vim), but that does make some sense. I was thinking of something you executed (perhaps during build), which altered the POD. The simplest example might be auto generated function signature in the METHODS section in the __END__ POD. Imagine code that could iterate through the methods, and then intelligently put at least the function name, and argument names at the end. The issue is really maintenance. Of course you can split the editor and look at both places, but wouldn't you rather something tell you you need to fill in info for a new function (this is essentially what pod-coverage.t in Module::Install does...it finds functions you don't have descriptions for). So I'm really looking for some sort of perl-ish forward generator of part of the POD.

Note that pmtools has something that finds all the functions in a module (but if you do "use" which everyone does, then it "pollutes" the namespace, and makes it hard to tell what is a native function and what is not.

So there are tools that do some types of auto-inspection, which could be looked at to see how this is done. But note you'd have to adhere to some conventions for it to work.

Folding requires clicking on +/-.

Clicking? In my Vim? :O

On a more serious productive note,

Imagine code that could iterate through the methods, and then intelligently put at least the function name

makes me think of golf~

And you didn't even know bears could type.

Now I understand better what you want (though still stay on my own :). I never heard about module that can do exactly what you want, and can't find anything on CPAN, so maybe you have to write it yourself. I think Pod::Coverage would be useful for you, it can find undocumented functions, but can't insert descriptions for them.

Not sure it has to do with prerogatives. Clearly, keeping the comments at the function head is the simplest to _maintain_. But for the aforementioned reasons, having a long comment about how a function works _obscures_ the code near it and makes it hard to _read_. In addition, any comments not immediately helpful to the maintainer make the _code_ harder to maintain. Now this normally isn't a problem because programmers don't actually write documentation (see most perl modules for evidence). Thus, having a small amount of documentation for each function isn't a big deal. The problem comes when you have _more_ documentation than the cursory few lines. Obviously it's great if you can keep your comments brief, but what if more explanation is needed?

Clearly someone in charge agrees with me as the existence of "__END__" demonstrates.

My editor has folding. I don't use it. I put the pod with the function. It's easier to maintain, and I don't find any problem doing a "find" on the function I'm interested in and hitting "next" once or twice. Or hitting the "next function" key combo. Really, it's not the issue (for most of us) that you make it out to be. Further, I strongly, strongly disagree with your statement that this makes the code harder to maintain. The code's comments (and external API) are part of the code. Separation is going to lead to disparity, which is then a bug in the code (since the docs are part of the code). To me, one of the points of intermixing POD with code is the huge convenience of colocation of code and comments making it at least plausible to keep them in sync. Which, interestingly, is also the way that Doxygen or even Javadoc. I suspect these guys know just as much about this as do the guys designing Perl when they encourage intermixing of code and documentation.

As for the existence of __END__, I'm not sure you realise that it's merely a point for the interpreter to stop and leave the file pointer in case you want to read it with the *DATA filehandle. It allows you to embed data in your source file without actually making it in your source. Many people put their POD there, but I'm not sure that's the purpose of it, merely a blessed way to use it. Personally, I think that's premature optimisation - putting it there prevents the perl parser from wasting valuable cycles looking past the POD, because it has stopped interpreting by then. But if you do things this way, then you'll never be able to use __END__ in its other manner: to provide a marker for your *DATA filehandle. If you do, then YOU will be responsible for ignoring the POD, and, personally, I'd rather that Perl's C-based interpreter skipped the POD than for me to write my own (or adapt an existing module) which can't be any faster than the native code. It's just code I don't see a need to write or maintain, just for some "convenience" (your meaning, not mine) of keeping my code easy to find.

OK, I think I see the issue. I'm expecting everything to be rosy when I'm reading this via less, or without editor help.

So then the question becomes "suppose you didn't have 'POD folding' in an editor and wanted to put the method descriptions at the end. Are there any perl tools that automatically help to keep the end METHOD section synchronized?"