# spl documentation - Thread: https://externals.io/message/36954 - Original archive: https://news-web.php.net/php.internals/36954 - Started by Alexey Zakhlestin on 2008-04-11T15:16:13+00:00 - Messages: 12 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #36954 — Alexey Zakhlestin — 2008-04-11T15:16:13+00:00 URL: https://externals.io/message/36954#36954 I noticed, that http://www.php.net/~helly/php/ext/spl/ was updated almost a year ago. Is the newer version available anywhere? -- Alexey Zakhlestin http://blog.milkfarmsoft.com/ --- ## #36956 — David Coallier — 2008-04-11T15:42:53+00:00 URL: https://externals.io/message/36954#36956 · In reply to: #36954 > I noticed, that http://www.php.net/~helly/php/ext/spl/ was updated > almost a year ago. Is the newer version available anywhere? > Good point, there're so many new things in there. Marcus? Etienne? Anyone up to do regenerate some docs ? Thanks, D --- ## #36958 — Etienne Kneuss — 2008-04-11T16:55:16+00:00 URL: https://externals.io/message/36954#36958 · In reply to: #36956 Hi, I've a more recent build that covers DLLists, but only Marcus is able to upload it to ~helly. I guess a new version will be online as soon as I finish documenting Heaps and priority queues. Regards > > > […] > > Good point, there're so many new things in there. Marcus? Etienne? > Anyone up to do regenerate some docs ? > > Thanks, > D > > -- > > > > > -- Etienne Kneuss http://www.colder.ch Men never do evil so completely and cheerfully as when they do it from a religious conviction. -- Pascal --- ## #36959 — Philip Olson — 2008-04-11T17:29:48+00:00 URL: https://externals.io/message/36954#36959 · In reply to: #36958 > > […] > > I've a more recent build that covers DLLists, but only Marcus is > able to > upload it to ~helly. > > I guess a new version will be online as soon as I finish documenting > Heaps > and priority queues. I think all effort should go into writing real documentation within the phpdoc cvs module instead of unreadable and unofficial doxygen output. Personally I feel the link to the doxygen output should be removed from php.net/spl (but won't) so anyway those are my feelings. Etienne is planning to work on both, which is great, but I encourage everyone to update the official spl documentation and not worry much about doxygen. Regards, Philip --- ## #36962 — David Coallier — 2008-04-11T17:46:00+00:00 URL: https://externals.io/message/36954#36962 · In reply to: #36959 > > I think all effort should go into writing real documentation within the > phpdoc cvs module instead of unreadable and unofficial doxygen output. > Personally I feel the link to the doxygen output should be removed from > php.net/spl (but won't) so anyway those are my feelings. Etienne is planning > to work on both, which is great, but I encourage everyone to update the > official spl documentation and not worry much about doxygen. > I agree with you on the part that efforts should be put for the phpdoc but I personally consider doxygen's output to be much more complete than any phpdoc output. The doxygen output is very technical and usually if you are looking for something very specific, you'll find it. PHPDocs and Doxygen outputs are really 2 separate beasts, for instance with Doxygen you'll see a clear hierarchy between the objects/classes and which classes they inherit and implement whereas the phpdoc will describe the functions clearly. There are many things that doxygen does that phpdoc doesn't do and the same for phpdoc and doxygen. Anyways, I think we still need that doxygen output and it would be plain bad to scrap it. D --- ## #36964 — Stanislav Malyshev — 2008-04-11T18:15:40+00:00 URL: https://externals.io/message/36954#36964 · In reply to: #36959 Hi! > I think all effort should go into writing real documentation within the > phpdoc cvs module instead of unreadable and unofficial doxygen output. I think having core module that is documented by doxygen is a shame. And if there's anybody working on docs, the work should be done first on official docs in the manual, which right now are in the "virtually non-existent" state. Doxygen is a nice thing but no replacement for real documentation. -- Stanislav Malyshev, Zend Software Architect stas@zend.com http://www.zend.com/ (408)253-8829 MSN: stas@zend.com --- ## #36965 — David Coallier — 2008-04-11T18:23:45+00:00 URL: https://externals.io/message/36954#36965 · In reply to: #36964 > > I think having core module that is documented by doxygen is a shame. And if > there's anybody working on docs, the work should be done first on official > docs in the manual, which right now are in the "virtually non-existent" > state. Doxygen is a nice thing but no replacement for real documentation. > Jesus christ! What's the amplitude this is taking ? We are not talking about keeping SPL ONLY documented in Doxygen, it's simply a nice addition to have it __DOT__. The only thing that Alexey asked was if there was some regenerated docs. Please, if you feel like you still have problems with SPL in the core or any other problems with documentation of extensions because of it's documentation, just start another thread. This one should be long over, the point was just to ask Marcus to put a new generated version online not to start a war on SPL's doxygen's documentation. Thanks, D --- ## #36966 — Ryan Panning — 2008-04-11T19:09:33+00:00 URL: https://externals.io/message/36954#36966 · In reply to: #36965 David Coallier wrote: > The only thing that Alexey asked was if there was some regenerated > docs. Please, if you feel like you still have problems with SPL in the > core or any other problems with documentation of extensions because of > it's documentation, just start another thread. This one should be long > over, the point was just to ask Marcus to put a new generated version > online not to start a war on SPL's doxygen's documentation. > > Thanks, > D I'll start the new thread. ;) I think the point being that the PHPDOC for SPL is limited is valid. There are some things that PHPDOC seems to cover better than Doxygen does and vise versa. From a PHP developer standpoint, it would be nice if PHPDOC had more than just "see the Doxygen docs". Doxygen does cover the OO in good detail, and that is nice. But some things are not explained well enough like PHPDOC. So, personally I'd like to see PHPDOC explain what each class/method is and how to use them. Then have the Doxygen detail the reflection kinds of stuff for the classes. --- ## #36976 — Gregory Beaver — 2008-04-12T00:14:12+00:00 URL: https://externals.io/message/36954#36976 · In reply to: #36959 Philip Olson wrote: > > > […] > > > […] > > I think all effort should go into writing real documentation within the > phpdoc cvs module instead of unreadable and unofficial doxygen output. > Personally I feel the link to the doxygen output should be removed from > php.net/spl (but won't) so anyway those are my feelings. Etienne is > planning to work on both, which is great, but I encourage everyone to > update the official spl documentation and not worry much about doxygen. +1 This finally makes sense with the new doc style, which is OO-friendly. Greg --- ## #36979 — Antony Dovgal — 2008-04-12T00:34:19+00:00 URL: https://externals.io/message/36954#36979 · In reply to: #36966 > David Coallier wrote: > > […] > > I'll start the new thread. ;) JFYI: you don't start a new thread by replying to an email from another one. Your reply still belongs to the original thread. -- Wbr, Antony Dovgal --- ## #37179 — Marcus Boerger — 2008-04-22T16:24:34+00:00 URL: https://externals.io/message/36954#37179 · In reply to: #36959 Hello Philip, Friday, April 11, 2008, 7:29:48 PM, you wrote: > > […] > > […] > I think all effort should go into writing real documentation within > the phpdoc cvs module instead of unreadable and unofficial doxygen > output. Personally I feel the link to the doxygen output should be > removed from php.net/spl (but won't) so anyway those are my feelings. > Etienne is planning to work on both, which is great, but I encourage > everyone to update the official spl documentation and not worry much > about doxygen. Personally I tried for year to get some feedback on getting documentation to support classes. And we still do not have any acceptable support. So I went on and provided all documnetation in source code. That said there should be three easy ways to proceed: 1) delete all my documentation and/or simply ignore what I did and write whatever documentation you guys want. The code I use for doxygen would still be useable to understand the code and even allows to replace parts of SPL on installations of PHP prior to 5.3 where SPL is disabled. 2) Do not change anything at all and continue to improve the documentation on php.net. Obviously in both versions we might be thinking of keeping or removing the link to my doxygen stuff. 3) Finally support inheritance in the documentation and either generate inheritance- and call-graphs for the manual or simply use doxygens xml format and png output to generate the graphs for the manual. This way we could even use the docu in the example/replacement code as a basis for the manual. Maybe this explains why there is the doxygen stuff. And just once more: I never tried to overthrow the manual or be better or replace it or whatever. In fact I only wanted to get the graphs and never got any help to improve the docs in anyway. So any help to improve the docs are welcome. Now regarding updates. Updates will come as there is something to update. The situation is that I could regenerate the doxygen outpiut. But all we would get is a manual for unreleased features. In other words the current doxygen output should reflect the current state, that is 5.2. marcus --- ## #37180 — Stanislav Malyshev — 2008-04-22T17:06:29+00:00 URL: https://externals.io/message/36954#37180 · In reply to: #37179 Hi! > Personally I tried for year to get some feedback on getting documentation > to support classes. And we still do not have any acceptable support. So I My impression is PhD now supports classes quite well. There are even skeletons as I understand :) I wonder how hard would it be to write a script to generate half-baked docbook files from the same data doxygen works with (my guesstimate would be couple of days effort, but that's just a guess :) for later manual editing. > 1) delete all my documentation and/or simply ignore what I did and write > whatever documentation you guys want. The code I use for doxygen would I think deleting any docs would be a waste, and doxygen docs definitely have its use. They just don't replace the manual. > 3) Finally support inheritance in the documentation and either generate > inheritance- and call-graphs for the manual or simply use doxygens xml I think manual needs just plain old method descriptions, etc. much more that inheritance graphs. Not to say those can't be useful - they can - but right now we don't have even the bare minimum - list of classes and methods which may say in plain text what inherits what. Once we have that, we might proceed to doing more cool stuff like inheritance graphs. -- Stanislav Malyshev, Zend Software Architect stas@zend.com http://www.zend.com/ (408)253-8829 MSN: stas@zend.com