Devel-Comments version 1.1.4

DEVELOPER README

"I get the feeling that the computer just skips over all the comments."
    -- a grad student

Devel::Comments is a source filter for your Perl code, intended to be used 
only during development. Specially-formatted 'smart' comments are replaced by 
executable code to dump variables to screen or to file, display loop 
progress bars, or enforce conditions. These smart comments can all be 
disabled at once by commenting out the 'use Devel::Comments' line, whereupon
they return to being simple, dumb comments. Your debugging code can remain in 
place, guaranteed harmless, ready for the next development cycle. 

Devel::Comments is a fork of Smart::Comments; the intention is to add new 
features without breaking backward compatibility. Version 1.1.2 implements the
'any filehandle' feature, allowing smart output to go to any filehandle 
opened for writing. You may instead pass in a filename, which DC will open for 
you. Future plans include extended calling syntax, numerical level enabling, 
improved progress bars, dump method callback, and execution of arbitrary code. 
Bugs raised against Smart::Comments 1.0.4 will be fixed in DC. 


FOR DEVELOPERS

Please feel free to email me at <xiong@cpan.org>. 
You can also use the wiki at: 
<http://github.com/Xiong/devel-comments/wiki>.

Please read files under notes/, especially notes/DEVELOPER.

Smart::Comments is good but it writes all its output to STDERR. 
This conflicts with testing frameworks that capture STDERR for testing. 
It probably also doesn't work well with, say, a CGI script. 

The intent of Devel::Comments is to allow output 
    to any file or filehandle, especially to a disk file. 

If *STDERR is passed in on the use line or no filehandle at all, 
        then ::Any behaves exactly like vanilla Smart::Comments. 

Previous plan involved a future module Smart::Comments::Log. 
    This is no longer planned. ::Any will do it all. 

2010-07-05:

Per-call state info is stored in $state_of{$caller_id}, 
    where $caller_id is assigned arbitrarily at time of use(). 
    
    This is nearly fully implemented. Vanilla stores some state info
        for progress bars in caller's namespace. TODO: Fix. 

All tests originally packaged with Vanilla now pass ::Any, 
    with the note that these tests originally were a bit too finicky when
    checking smart output in case of a failed assertion. 
    
    See e.g., t/0100-va/31-assert.t for explanation. 

Tests pass in which an opened filehandle is given in the use line. 

TODO: 

    * Publish new git workflow plan more or less 
        per http://nvie.com/git-model
        and restage github repo to match. 
    
    * Rewrite prefilter() to consolidate argument parsing
        and deal with opening files when a filename is passed in
        and deal with args passed in, in a hashref. 
    
    * Time for docs cleanup. Check all block comments, POD, loose notes files. 
    
    * Prepare release. Decide on version numbering system. 

-Xiong Changnian 2010-07-05 16:12:07

2010-11-15:

Mike Stok raised the excellent point that POD and code do not agree on 
    the point of environment variable handling. 

He has been kind enough to supply a strategy and a patch implementing it. 

2011-08-07:

Kevin Ryde discovered a case where smart output just looks ugly: 
    the raw Data::Dumper code just doesn't get cleaned up decently. 
    This has been fixed.