Yii Framework Forum: Switch description and params list in documentation? - Yii Framework Forum

Jump to content

Page 1 of 1
  • You cannot start a new topic
  • You cannot reply to this topic

Switch description and params list in documentation? Rate Topic: -----

Poll: Switch description and params list in documentation? (5 member(s) have cast votes)

Switch description and params list in documentation?

  1. Yeah, that would make reading a bit easier... (2 votes [40.00%])

    Percentage of vote: 40.00%

  2. Nay, it's OK like it's organized right now... (3 votes [60.00%])

    Percentage of vote: 60.00%

Vote Guests cannot vote

#1 User is offline   Trejder 

  • Master Member
  • PipPipPipPip
  • Yii
  • Group: Members
  • Posts: 1,197
  • Joined: 06-October 10
  • Location:Southern Poland

Posted 28 November 2011 - 04:13 AM

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.
Proud Cookbook author, though still learning powerful Yii! :] See my generic profile for more information. Cheers!
1

#2 User is offline   MadAnd 

  • Standard Member
  • PipPip
  • Yii
  • Group: Members
  • Posts: 109
  • Joined: 16-June 11
  • Location:Ukraine

Posted 28 November 2011 - 06:12 AM

Hi,

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.
0

#3 User is offline   Maurizio Domba Cerin 

  • Yii - Yesss It Is !!!
  • Yii
  • Group: Yii Dev Team
  • Posts: 4,355
  • Joined: 12-October 09
  • Location:Croatia

Posted 30 November 2011 - 03:20 AM

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...
Find more about me.... btw. Do you know your WAN IP?
0

#4 User is offline   Trejder 

  • Master Member
  • PipPipPipPip
  • Yii
  • Group: Members
  • Posts: 1,197
  • Joined: 06-October 10
  • Location:Southern Poland

Posted 30 November 2011 - 07:51 AM

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.
Proud Cookbook author, though still learning powerful Yii! :] See my generic profile for more information. Cheers!
0

Share this topic:


Page 1 of 1
  • You cannot start a new topic
  • You cannot reply to this topic

1 User(s) are reading this topic
0 members, 1 guests, 0 anonymous users