Re: [PHP-DOC] Re: Function Index
2009/3/31 Philip Olson : > So is there anything I can do? > >>> My question is, were those statistics about undocumented functions etc. a >>> result of problems with PhD or a genuine reflection of functions that are >>> missing documentation? My guess is the latter... > >> How feasible would it be to add a "to" attribute to the version.xml >> entries. >> >> It should move us towards getting a more accurate index. >> >> The issue of OOP/procedural entries is akward, but theoretically, they >> should be indexed separately as MAYBE the OOP interface was added at a >> later date. > > Having separate OO entries is one step as some do it whereas others do not. > The files need cleaned up if they are going to be used for tasks like > creating a base for funcindex.xml because for various reasons they are not > meant for this. Results for "undocumented" happen for many reasons, as > described earlier. Summary of them: > > - Current reliance on formatting by both configure.php and Phd (ex. - vs _) > - We don't document many of the old aliases, yet keep version information > (which is fine) > - OO versus Procedural tracking and formatting -- is inconsistent > - They are in fact not documented (these are okay to have in the > funcindex.xml) > - All versions.xml are not perfect (I assume other problems exist too) > > However, let's realize that versions files are meant to perform one task: > track version information. That said, what would this "to" attribute mean or > do? > The life of a function started with a particular PHP/PECL version (the "from" attribute"). If a function is deprecated, you could either incorporate the final version into the "from" attribute in some way or have a "to" attribute. The "to" attribute would provide a clear indication of the final version of the function/method. Only those functions without a "to" attribute would be considered "live". With this attribute version.xml would now be tracking the entire life of the function/method in an easy to use way. > Summary: As is the version files work [almost] perfectly for the current > task, but not for any other. And many of the "undocumented" results are > bogus. > > Regards, > Philip > > > -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 "Standing on the shoulders of some very clever giants!"
Re: [PHP-DOC] Re: Function Index
So is there anything I can do? My question is, were those statistics about undocumented functions etc. a result of problems with PhD or a genuine reflection of functions that are missing documentation? My guess is the latter... How feasible would it be to add a "to" attribute to the version.xml entries. It should move us towards getting a more accurate index. The issue of OOP/procedural entries is akward, but theoretically, they should be indexed separately as MAYBE the OOP interface was added at a later date. Having separate OO entries is one step as some do it whereas others do not. The files need cleaned up if they are going to be used for tasks like creating a base for funcindex.xml because for various reasons they are not meant for this. Results for "undocumented" happen for many reasons, as described earlier. Summary of them: - Current reliance on formatting by both configure.php and Phd (ex. - vs _) - We don't document many of the old aliases, yet keep version information (which is fine) - OO versus Procedural tracking and formatting -- is inconsistent - They are in fact not documented (these are okay to have in the funcindex.xml) - All versions.xml are not perfect (I assume other problems exist too) However, let's realize that versions files are meant to perform one task: track version information. That said, what would this "to" attribute mean or do? Summary: As is the version files work [almost] perfectly for the current task, but not for any other. And many of the "undocumented" results are bogus. Regards, Philip
Re: [PHP-DOC] Re: Function Index
2009/3/31 G. T. Stresen-Reuter : > On Mar 31, 2009, at 11:04 AM, Richard Quadling wrote: >> >> So is there anything I can do? >> >> -- - >> Richard Quadling > > My question is, were those statistics about undocumented functions etc. a > result of problems with PhD or a genuine reflection of functions that are > missing documentation? My guess is the latter... > > Thanks in advance. > > > > G. T. Stresen-Reuter > Web: http://tedmasterweb.com > Blog: http://tecnotertulia.com > Twitter: http://twitter.com/tedmasterweb > > > > How feasible would it be to add a "to" attribute to the version.xml entries. It should move us towards getting a more accurate index. The issue of OOP/procedural entries is akward, but theoretically, they should be indexed separately as MAYBE the OOP interface was added at a later date. -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 "Standing on the shoulders of some very clever giants!"
Re: [PHP-DOC] Re: Function Index
On Mar 31, 2009, at 11:04 AM, Richard Quadling wrote: So is there anything I can do? -- - Richard Quadling My question is, were those statistics about undocumented functions etc. a result of problems with PhD or a genuine reflection of functions that are missing documentation? My guess is the latter... Thanks in advance. G. T. Stresen-Reuter Web: http://tedmasterweb.com Blog: http://tecnotertulia.com Twitter: http://twitter.com/tedmasterweb
Re: [PHP-DOC] Re: Function Index
2009/3/26 Philip Olson : > Greetings, > > I'm not really offering a solution here but will point out some problems and > considerations after looking at: > > - A diff of the generated funcindex.xml versus the current in CVS > - The function index to see which are considered undocumented in the new > funcindex > - How phd manipulates version.xml information for the phpdotnet theme > > A few reasons why some appear undocumented: > > Old Dead API and/or aliases: > - Ex: bcompile_* versus bcompiler_*. > - Ex: date_time mess, most of these existed in one old pecl extension only > - Ex: MySQL, like mysql_numrows vs mysql_num_rows > OOP versus Procedural > - Ex: xmlwriter, mysqli, ... > > And other notes that may or may not relate to the above or each other: > > - Seems WeLoseSomeCamelCasing for understandable reasons but it's a thought > to consider > - version.xml files are not perfect, but should be (Ex: maxdb-affected-rows > being removed from funcindex) > - dom versus domxml: not sure where to begin on this as it's a mess on so > many levels > - _ versus - as both are used in versions.xml so end up in funcindex as is > (ex: printer-draw-text()), see below > - Many mysqli entries were removed but not replaced, see below > > Some of the above may be attributed to how versions.xml files are handled by > PhD because it's somewhat of a [smart?] hack currently. Often times when an > extension offers both OOP and Procedural only one is documented in > versions.xml because they are usually documented on the same page... so it > works. Bad? But because of this we end up with one seen as undocumented in > the newly generated funcindex.xml. > > Also, the phd versions conversion mechanism hack (ex: - to _, :: to _) > allows versions.xml files to be written in all sorts of styles, so > funcindex.xml ends up ugly as it doesn't keep these in mind. I don't know > the best way to handle this offhand but the problem exists. > > Summary for version files: They are both liberal (with old API information, > deprecated goodies) and abbreviated (by often missing version information > for OOP/Procedural companions) so basically they require cleaning before use > for other purposes aside from adding version information to the PHP Manual. > > Regards, > Philip > > > So is there anything I can do? -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 "Standing on the shoulders of some very clever giants!"
Re: [PHP-DOC] Re: Function Index
Greetings, I'm not really offering a solution here but will point out some problems and considerations after looking at: - A diff of the generated funcindex.xml versus the current in CVS - The function index to see which are considered undocumented in the new funcindex - How phd manipulates version.xml information for the phpdotnet theme A few reasons why some appear undocumented: Old Dead API and/or aliases: - Ex: bcompile_* versus bcompiler_*. - Ex: date_time mess, most of these existed in one old pecl extension only - Ex: MySQL, like mysql_numrows vs mysql_num_rows OOP versus Procedural - Ex: xmlwriter, mysqli, ... And other notes that may or may not relate to the above or each other: - Seems WeLoseSomeCamelCasing for understandable reasons but it's a thought to consider - version.xml files are not perfect, but should be (Ex: maxdb- affected-rows being removed from funcindex) - dom versus domxml: not sure where to begin on this as it's a mess on so many levels - _ versus - as both are used in versions.xml so end up in funcindex as is (ex: printer-draw-text()), see below - Many mysqli entries were removed but not replaced, see below Some of the above may be attributed to how versions.xml files are handled by PhD because it's somewhat of a [smart?] hack currently. Often times when an extension offers both OOP and Procedural only one is documented in versions.xml because they are usually documented on the same page... so it works. Bad? But because of this we end up with one seen as undocumented in the newly generated funcindex.xml. Also, the phd versions conversion mechanism hack (ex: - to _, :: to _) allows versions.xml files to be written in all sorts of styles, so funcindex.xml ends up ugly as it doesn't keep these in mind. I don't know the best way to handle this offhand but the problem exists. Summary for version files: They are both liberal (with old API information, deprecated goodies) and abbreviated (by often missing version information for OOP/Procedural companions) so basically they require cleaning before use for other purposes aside from adding version information to the PHP Manual. Regards, Philip
