Re^4: Meta-perl - sorting my perl subs with perl?

Replies are listed 'Best First'.
Re^5: Meta-perl - sorting my perl subs with perl? by JavaFan (Canon) on Jan 23, 2012 at 16:17 UTC
POD != comment. The intended audience is different. If you treat them as the same, both sides will suffer. Comments are for the programmer, that is, the person maintaining the code. POD is there to create a manual. The intended audience is the user of the code. I usually do not document my subs in the same order as they appear in the file, and I typically have quite a number of subs that will not be documented in the user manual. And I want to be able to reorder my subs, or my documentation, without having to reorder the other. have to duplicate your POD in a comment. So what? If the goal is to minimize the work you need to do as a programmer, don't write any POD or comments. If the the goal is to create a better product, I don't care if there's some duplication going on. Copy and paste is cheap and easy. (But it will be a selective copy and paste anyway).	[reply]
Re^6: Meta-perl - sorting my perl subs with perl? by educated_foo (Vicar) on Jan 23, 2012 at 16:46 UTC
Not really -- programmer documentation is for the programmer. "C-h f" shows the doc-string. If I want to see what a function does, I type "C-h f"; if I change a function, I edit the doc-string it contains. Emacs also has a manual -- written in the god-awful Texinfo format and updated by hand -- that provides higher-level documentation. FWIW, I try to document my modules with POD next to each public function and a higher-level description at the end.	[reply]
Re^7: Meta-perl - sorting my perl subs with perl? by JavaFan (Canon) on Jan 23, 2012 at 18:15 UTC
Who is "the programmer" here? The person maintaining the function? Or the person using the function? Two different people. Two different sets of documentation. If it's only available using a specific editor, both people lose.	[reply]
Re^8: Meta-perl - sorting my perl subs with perl? by educated_foo (Vicar) on Jan 24, 2012 at 16:46 UTC
Re^9: Meta-perl - sorting my perl subs with perl? by JavaFan (Canon) on Jan 24, 2012 at 21:13 UTC
Some notes below your chosen depth have not been shown here
Re^5: Meta-perl - sorting my perl subs with perl? by LanX (Saint) on Jan 24, 2012 at 17:11 UTC
> After getting used to Emacs's docstrings, I find that style annoying BTW: One of the clear advantages of Python are docstrings. I agree to a certain point, that docstrings are perfect for "source" documentation for maintainers. If it comes to "usage" documentation separated POD is IMHO better to show the big picture. Since this thread is about extracting subs we are clearly talking about the first kind of documentation I regularly tried to have discussions on that matter (since there is a big overlap between both kind of documentation) but that normally ends in flame wars... :( Cheers Rolf	[reply]