On 30 January 2013 09:37, Ferenc Kovacs <tyr...@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
