Would love to see something like an ajaxified section below method or prop details that would expand to show couples of practical examples in the class reference page, anyone else?
Would love to see something like an ajaxified section below method or prop details that would expand to show couples of practical examples in the class reference page, anyone else?
Practical code examples are invaluable when learning a framework but an API documentation shouldn’t be turned into a “Beginner’s Guide to Yii”. Both have its own importance but they serve different purposes and shouldn’t be confused with each other.
I agree with the OP, while the documentation is great the way it is, a few examples would make a lot of the syntax more clear to beginner users.
I cannot agree more
This is really a doomed question IMO. 
The documentation of PHP or jQuery are full of examples and useful comments…
An idea is to built a separate page with practical examples and community contributions where the documentation pages could refer to
By the way, practical examples aren’t just for beginners, I regularly copy paste snippets of code just out of laziness 
does the comment sections intend to contain examples? The only disadvantage is that you comment whole class, not a single method…
I for one learn by doing and by examples. I can read how to do things but I always end up trying to find examples on how to do something. Otherwise, I end up continually reading, getting information overload and never really implement something.
Completely agree, one example could actually sums up the whole documentation’s wall of text on a subject.
Yii offers many useful tools, we don’t have any problems there, however, I sometimes find myself stuck on deciding when to use which tool. I actually know “how to use” them but the API and documentation are not clear enough to direct beginners with good suggestions. Adding a when to use guide along with each class/method could clarify most of the problems people have and reduce the learning curve considerably.
Yes, this would be helpful to put certain Objects/Class into a context. It’s often hard to do this without examples, for examples the Cache components. So there seems to be a class named “CDbCache”, but “How to use it? What to do with this object?” were questions I often had.
The examples don’t have to cover every method call but rather display how these objects can be used.