... since you likely can't embed pod in a .c source file.

You can use POD in any language that has multiline comments. In the case of C you'd just put your POD between the /* ... */ markers.

To your specific question, I always put the POD right in the code, and use Test::Pod and Test::Pod::Coverage to make sure the POD follows some type of standard. In my application's t/ directory I always put the following files:

$ cat t/02pod.t
use strict;
use warnings;
use Test::More;

eval "use Test::Pod 1.14";
plan skip_all => 'Test::Pod 1.14 required' if $@;
plan skip_all => 'set TEST_POD to enable this test' unless $ENV{TEST_P
+OD};

all_pod_files_ok();

$ cat t/03podcoverage.t
use strict;
use warnings;
use Test::More;

eval "use Test::Pod::Coverage 1.04";
plan skip_all => 'Test::Pod::Coverage 1.04 required' if $@;
plan skip_all => 'set TEST_POD to enable this test' unless $ENV{TEST_P
+OD};

all_pod_coverage_ok();
[download]

In other words, I dont recommend putting POD in its own file for application documentation.

regards,

Thank you, this is of some help.

Very useful to know putting pod in /* comments */ would do it.
I really appreciate your suggestion about t/, I will implement. Very classy solution.

Personally, putting pod in its own files has helped me maintain the code. It's a little tiny bit more a pain to have more files to keep track of.
I find that having the .pod files draws me to the fact that I have to document.
It helps me keep track of what the API is supposed to do.
I may write a .pod file as an idea and come back later to consolidate reality with plan.

It helps to have both code and doc open next to each other- to go back and forth- yes yes.. I know.. two windows on vi.. Somehow I'm still a mere mortal here.

What are some concrete reasons for which you suggest against the practice mentioned?

I didnt really clarify because I guess its something one could go on talking about forever if sufficiently interested.

I don't exclusively put POD in modules. I also do like you say. I use POD in the docs/ directory... put it in html comments... all over the place.

But for the developer documentation, my rule is that the POD for a given method goes directly above that method. I've developed this convention because I use Catalyst a lot and it generates POD when you make a stub controller.

regards,

It's when you install your module when POD gets turned into manual pages, and gets installed.

Now, perldoc, that's a different matter. That does on the fly search and parse. perldoc search @INC. Which basically means that if perl -MModule -e1 compiles, perldoc can find the POD for Module.

See Pod::Select. You could include a podselect() run for your example/* and bin/* files into your make process, to stuff the resulting pod files into the lib/MyModule/ directory of your distribution.