Embedded documentation writers

I think any good programmer knows that any time you write code that relies on being updated in two different places any time you need to make a change, you are destined for some kind of catastrophe some time in the future. I think it is a rather minor extension to also say that failure to update your documentation whenever you make a change in your module's functionality is also a formula for trouble, or at least great inconvenience. Take the following code for example:

## Set FORKING_CHILDREN to zero to turn off forking
use constant FORKING_CHILDREN => 0;

...  ## Pages and pages of un-related code here.

=item C<some_function>

Here is my pod for some function.  In this function,
you are allowed to specify one parameter, the number of
forking processes.  You may turn parallel mode off by
setting the number of processes to zero.  If you neglect
to provide a value, then the default value of 0 will be
used.

=cut

That's a very basic example, but imagine the potential grief that you could cause somebody that is using your code if you later decide to set FORKING_CHILDREN to 1, or 5, or 200... and neglect to update the pod.

I suppose somebody might say, "Well, that's the programmers fault, because they should always update their documentation every time they make a change." But I would argue that while the burden of documentation is definitely upon the programmer, there is a greater burden of coding responsibly such that changes in one place of code do not necessitate changes in other places of the code. What I would rather see in the above example is a way to modify my constant value and have my pod automatically updated.

People who have experience using Concurrent Versioning System (CVS), are familiar with embedding tags that get substituted at commit time. For example, if you add the code $Revision$ into your text and commit it to CVS, then your code will be modified to include the present revision number of your code, like this: $Revision: 1.3. I wonder how easily such a system could be embedded into pod?

And while I'm on a roll, I would suggest that rather than invent a new language that can handle variable substitution and any other tricks we want to be able to do, why not just re-use a language that has already been written? Why not just be able to embed Perl code to write our documentation?

What I would love to see is something where I can write this:

=pod

=item C<my_function>

Here is some documentation, it is nice documentation.

=begin perl

print "The default value is ", ($default) ? 'ON' : 'OFF';

=end

=begin generated_pod

The default value is ON

=end generated_pod

In the above example, I would expect to be able to write the the perl text, and then have perl automatically insert the generated_pod text the next time I ran perl with the correct switch. When I run perldoc, the perl text would be ignored, and the generated_pod text would be considered equal to normal pod. The next time I run perl with the appropriate switch, all generated_pod sections would be removed, and then re-generated.

Re-Using pod

The other thing that I encounter quite a bit in object-oriented programming is a situation where I am sub-classing some existing module or joining multiple modules so that I can add new functionality, or create an interface for some specific task at hand. The problem is that I run into a 'lesser of two evils' situation.

I usually want to be able to provide a complete API for somebody to use, meaning that they don't need to think about how I'm implementing it or where the functionality is coming from, and that they don't have to read four different perldocs at the same time to understand how to use it. But on the other hand, I don't want to import somebody else's pod into my code, because that would mean always updating my code every time somebody else updates their code. That would be a maintenance nightmare and lead to out of date pod very quickly.

A much better solution, in my humble opinion would again to be able to embed some tag that means "Insert some block of pod from a different file/module here". The idea being that as one file's pod is updated, your pod would be updated dynamically.

I see two approaches that could be taken for this. It could be implemented exactly the same as my above suggestion, where you have some substitution and text manipulation that is actually done by the compiler. The problem with this one is that your module might sit compiled on somebody's machine for a year without being updated, while somebody else's module the provides pod for your module could have been updated on the same machine monthly.

The second option that I see in this case would be to allow perldoc to implement the substitution on the fly without actually updating the source. In a situation where we have dynamic content, this is probably better, but it is at the expense of spending the cpu cycles every time you load the page, which could potentially take a while for pages which use pod from pages which use pod, etc.. Perhaps some switch could be added to perldoc to toggle the pod inclusion on and off.

Conclusion

These are just two observations / desires that I have about pod. I'm mainly throwing them out because I really would like to know what other people think about these ideas. I'm sure I'm not the only person to have ever thought about this, so I'm fully prepared to insert foot in mouth if it turns out that the things I'm looking for are already possible. On the other hand, I really can't find much talk about pod anywhere, save a few brief mentions here and there in various perl books. Am I alone in my quest for easier and better documentation?

UPDATED: Added readmore tag