Switch description and params list in documentation?

Am I the only one here just a little bit tired of scrolling down sometimes really long list of parameters just to see a function or property description in the documentation?

Shouldn’t it be / Wouldn’t it be easier, if it would organized just the way PHP docs are done? I.e.: function / property name, then description and then list of parameters, return results etc.


I think that there is much more convenient to see parameters descriptions right after function signature, rather then after description (which also sometimes is very large). So my vote is to leave current representation.

I guess…

it all depends on what you are searching… as beginners might search for the function description… but advanced users that knows what a function does - don’t need to read the description any more… they want to see the parameter order and what values the parameter can have…

I wouldn’t assume that even very experienced users or dev team members remember every function description! :]

I also can’t agree with MadAnd as I thing that there is only like 10 or less percent of functions and properties that has description longer than parameters list.

Yii was build on top of PHP. PHP documentation authors thinks that having description before parameters list is better. Does it means, we should assume that there are no PHP advanced users? :]

I think that the best solution would be to move descriptions before parameters list and introduce additional links (next to All Packages | Properties | Methods, in brackets) Show/hide functions descriptions. These links would work exactly like Show/hide inherited methods/properties links work. And, if we could store these new links’ settings in a cookie, so there would be no need to click it every time you visit a page, then we would have a perfect solution for both beginners and experienced ones.