Re^2: POD using __END__ with function comments

[zerohero]

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

[Lawliet]

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~

[zerohero]

+/- is allegorical. Replace with your editors version. Unless of course your editor is psychic.

[Lawliet]

Well, there is a huge difference between using the mouse to fold and using a keyboard. One is much more plausible than the other.

[zwon]

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.

[zerohero]

>> Now I understand better what you want (though still stay on my own :)

Yes, I think I'm beginning to understand what I wanted to ask as well. It's hard to state the exact question when one starts from a point of not knowing anything :)

.

I think the approach I will take is to write an emacs command in Perl (I only use Lisp once in a blue moon). The command will go through the functions in the buffer, and then reconcile those with the descriptions in the METHODS section beyond __END__. It'll allow one to re-run the command to add function descriptions (for functions you've left off), without altering what you've done (it'll do a diff of sorts), as well as flag functions you've deleted (which won't work perfectly for changing the names, but...). So by following some simple conventions I'll be able to keep the method documentation separate from the code (I'll probably put a line or two at the head of each function, but then extended docs below __END__).

This will let me have code that is both maintainable and more readable than the mix in way.