Re: svn: /phpdoc/en/trunk/reference/spl/splfileobject/ tostring.xml

On Jan 30, 2013, at 2:37 AM, Peter Cowburn wrote: > On 30 January 2013 09:37, Ferenc Kovacs <tyra3l@gmail.com> wrote: >> >> hi, >> >> could you please link the relevant page about this? >> >> <snip> >> >> Before I commited the change, I looked around, and every other alias under >> spl had the method synapsis with the exception of >> splfileobject/getcurrentline.xml(which should be also fixed depending on the >> outcome of this discussion): >> >> splobjectstorage/offsetunset.xml >> splobjectstorage/offsetexists.xml >> splobjectstorage/offsetset.xml >> splqueue/enqueue.xml >> splqueue/dequeue.xml >> >> So I think that the method should be listed in the synopsis (to avoid >> confusion), there are existing precedences for aliases between class methods >> having methodsynopsis and there is nothing (or at least I couldn't find) in >> the docs related to this, so nothing which would prohibit the methodsynopsis >> usage in this case. >> >> What do you think? >> > > The doc howto (usually at http://doc.php.net/php/dochowto which > is > broken, the source is in doc-base/howto) says that aliases should not > have the synopsis and should only direct readers to the aliased > function/method. [1] > > We break this rule in many SPL doc pages already, sometimes on > purpose. It probably happens elsewhere too. The reasons are twofold: > 1. many of the pages are little more than skeleton docs so have the > normal method page structure rather than the proper alias one; 2. It's > nice to have the method synopsis there since then those methods are > then listed in the class synopsis. > > Should we think about amending the howto with regards to maybe adding > in a synopsis for methods? Obviously that works against us in terms of > maintenance (more places to change should the method signatures > change) and cleanliness (the alias page's job is to redirect to the > appropriate fully-documented method). > > Or, is there a way to get these aliases showing up in the class > synopsis method list whilst keeping the alias page without a method > synopsis? > > [1] > http://svn.php.net/viewvc/phpdoc/doc-base/trunk/howto/working.xml?view=markup#l343 Hello friends, Sounds like we should add <methodsynopsis> to every SPL alias for now, and consider alternatives later. And this alias discussion reveals additional holes in the process of documenting aliases. For example, the following list: http://php.net/aliases This list is outdated, which suggests removal or a major overhaul. And it doesn't differentiate between deprecated, removed, or permanent aliases. But more on that later. And we add XML documents for some aliases. Which? I don't remember how exactly we decided to document aliases but I agree the likes of msql() (from the PHP 2 days?) do not require their own files/pages. Many of the old aliases would be deprecated->removed from PHP-src if someone presented the idea. Note: I am not presenting the idea. :) As for what to do, I recommend: a) We add <methodsynopsis> to all SPL aliases b) Be certain that every "Class synopsis" page is accurate And consider/discuss: c) List all aliases, and define the current and desired documentation status of each. How can we do this? Parse php-src? d) Add a <methodsynopsis> to all documented PHP method aliases? And functions? Would (d) help code-insight for IDEs? e) PhD improvements, regarding alias handling Thoughts? Regards, Philip