Switch description and params list in documentation?
Posted 28 November 2011 - 04:13 AM
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.
Posted 30 November 2011 - 03:20 AM
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...
Posted 30 November 2011 - 07:51 AM
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.