Update: "Documentation" here refers to documents in the areas of specification and implementation.

uses this same style for every environment

This style could be done inside POD instead of a Perl if statement with a slight gain in clarity. Just putting the if on top would help.

structured to be easily machine-parsible, and therefore usable in different contexts

But it is still not trustworthy.

such documentation means to balloon the size of the source

This is concise to me.

to include such documentation means to write two different

This is a problem of any documentation.

means to constantly make sure the docs are in synch

This is a problem of any documentation.

informal anectdotal psuedo-survey reveals that 'self-documenting' features of prog languages in general is one of the *least utilized* features for many production environments in the 'real world'

And something like three of four products fail to be created. My experience is limited but I tend to accept your pseudo-survey's accuracy. So what. That the masses don't use a feature indicates nothing about the quality of the feature.

Funny how the author can not be bothered to use Perl's integrated documentation features.

should the author be persecuted for not using POD?

Not really, firing for insubordination is sufficient in the business world. If the this is independent work and the writer can draw enough interest to make this an issue good for him.

is there ... such thing as 'self-documenting' code?

Perhaps in very limited problem scopes. Otherwise there are always areas where the constraints of a computer process impinge on the preferred conceptual model/solution.

It is a fine thing to strive to have the code and the documentation become one. What you are showing is code and documentation which are lexically adjacent; often the best that can be achieved.

what is an easier way to write source code that can be queried *itself* as if it were data or documentation?

I am not sure what you mean. I think things with encompassing IDE's (integrated devel. envir.) sometimes try to reach this, perhaps smalltalk. Eiffel tries to do this with its assertions, pre-conditions, etc. Knuth's Literate Programming is a tangled web you may wish to explore.

does anyone ... care?

Yes, Ugol's Law is applicable.

I don't find the sample convincing. The common problems of documentation survive. The name is bad; DispGreeting doesn't display anything.

I would write this more like:

# off hand code

sub make_greeting {
    # Return a greeting string, by default greet the world.

    croak "Bad parameter count to make_greeting" 
        unless @_ <= 1 and DEBUG;
    return "Hello " . ( $_[0] or "world" ) .".";
}
[download]

If I were trying to address the issues of metadata in a large environment. I would put data like this into a code generating environment of some sort.

function:  
    name: make_greeting
    scope: intra-language
    descr: Make a greeting to designee or, by default, world.
    doubts: Locale issues await. Low-level func.--orphan?!
    parameter count: 0-1
    parameters:
         param: name
             ord: 1
             type: string
             descr: Name of recipient of greeting
    error: die
    languages: perl
    type: string
    perl:  return "Hello " . ( $_[0] or "world" ) .".";
[download]