[PEPr] Comment on PHP::PHP_GenDocBlock

Travis Swicegood (http://pear.php.net/user/tswicegood) has commented on the proposal for PHP::PHP_GenDocBlock. Comment: I've given it a quick glance and it looks like a pretty useful package. There's some CS things to be addressed, but other commentators have already left notes on those. I would recommend checking out PHP_Beautifier package as it'll help you get pretty close automatically. One thing I did see that I personally wouldn't do is the use of "and" and "or" to chain function calls together. For example, I would change: [code] // PHP_GenDocBlock::run() $outfile = $outfile or $infile; [/code] To: [code] if (empty($outfile)) { $outfile = $infile; } [/code] To me, the latter reads more easily, but that's just a personal preference more than anything. In a repository like PEAR, the goal with my code is to make it as readable as possible to someone who's never seen PHP before. The original code I cited above uses lesser known conventions in PHP, so that'd be the main motivation for me to make the change. I would also rename gendocblock to php_gendocblock to avoid any possible naming conflicts and insure that's noticed on the system as a PHP related executable. The only other thing I noticed is that you can't specify a docblock template. To me it would be extremely useful to be able to run: [code] $ cat MyGreatCode.php | gendocblock --template-path /path/to/templates [/code] I'm not certain what the template files would look like. Personally, I would just make it a very simple PHP file along the lines of this as the /path/to/templates/class.php file: [code] /** * <?php echo $short_desc; ?> * * <?php echo $long_desc; ?> * * @author <?php echo $author; ?> ... etc., etc. [/code] Then I could specify my own docblock style (for example: skip lines between all tags, add license text to file level docblocks, etc.) in an external template file. All-in-all, this seems to be a very useful package. One thing I am curious about is the naming of the package. I'm thinking Docs_DocBlock_Generator would be a good name. As you might have noticed on pear-dev, I am trying to figure out how to name another doc generator - this one for TestDox. As there seems to be a lot of documentation related packages right now, maybe it's time to add a Docs sub-category to Tools and Utilities. Proposal information: http://pear.php.net/pepr/pepr-proposal-show.php?id=481 -- Sent by PEPr, the automatic proposal system at http://pear.php.net