Re: [REMINDER] Tools and Utilities::PDS

Hi Davey, I think the idea of having a more useful .phps is good, perhaps a good package name is PHP_Advanced_phps, or some other name that stresses the connection to .phps/highlight_file(). I also think your economy of code is good. I do have a few problems with the package as it stands that I would like to see fixed before a release, and some are major, so feel free to veto :) 1) it should use external files for all formatting. These don't have to be templates, but can be PHP files that are included to allow user formatting and customization. 2) Since it is a PEAR class, it should have an API to allow extension and customization of child classes. I would rename doHTML() to parseTokens() and have it only organize tokens by type, and apply a separate helper function toHTML(), which is specified as an option (in other words, the future PDS extension might use toXML() instead or even toFlash(), based on a constructor argument $outputFunc = 'toHTML'). In this way, users can extend parseTokens() to specify different groupings of tokens, and apply their own output functions to these groupings 3) As you say, the documentation should link to source code line. For this purpose, you could use PHP_Parser easily (just parse the source, grab the line number from the returned array, and use it to link, and add in <a name> for each line number) 4) For this purpose, I think the documentation is much too large. I would like to see more of a tabular look (don't have to use <table> for this) as the default look. 5) I'd like an option to hide all private elements, as technically, they should never be called or extended from outside the current class. I wonder if your functions should have @access protected for that reason Hope these comments are helpful :) Most of these points won't stop me from +1ing, but I want to see #1 and #2 before I give a +1, so I'll give a +1/2 :). PDS is a great idea and you've done good work. With those changes, I think it will be a really useful tool. Greg Davey wrote:

Hey, PDS stands for PHP Documented Source. You can see the original posts on this here: http://marc.theaimsgroup.com/?l=pear-dev&m=105318684503136&w=2 Latest source should be available from my HDD here: http://davey.is-a-geek.com/PDS/pds.pre.pds - if you have problems accessing I'll move it to my server. I have done some more work on this lately (not much, but have it working properly now) and think its ready to be marked as Alpha and released in a PEAR Package. The two things that needed to be fixed and that have been are: * Allowing for multiple params * Killing the script in the auto_prepend_file so that the code isn't run in a buffer and silenced (thats how it worked before but I hated it, now I set error_reporting(0) and trigger an E_USER_ERROR which kills it before it tries to parse the file) Things that need doing are: * Allowing for parsing of *all* apidoc @foo properly * Source/Doc cross referencing * Making the source a <ul> list so that the numbers are no selected if you want to highlight and copy the code * Make each line (an <li>) highlight when clicked (a la Zend Studio) * link to included/required files .pds files if they are found I'm going to check out PHP_Parser a little later to see if that can be used instead of reproducing its code in this. Also I've spoken to Greg about what sort of role phpDocumentor's code will play in this, and I think we've concluded that its not practical to use code from the phpDcoument 1.x codebase, but we've talked about how phpDocumentor 2.0 can be written to make it easier to hook into the apidoc parser. Voting currently stands at: 0 There was a lot of talk about this and feedback, which I've acted on, but mostly it was talk about using phpDocumentor code within it and then it kind of dejenerated into a phpDocumentor discussion. I look forward to response. - Davey