Re: Some clarification where pod files should reside in a distro

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

Comment on Re: Some clarification where pod files should reside in a distro Select or Download Code

Replies are listed 'Best First'.
Re^2: Some clarification where pod files should reside in a distro by leocharre (Priest) on May 13, 2009 at 20:50 UTC
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?	[reply]
Re^3: Some clarification where pod files should reside in a distro by trwww (Priest) on May 13, 2009 at 21:10 UTC
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,	[reply]