Snippets are good but not very easy to use (you don't go to snippets when you are searching something ...).
When you need to know how a widget can be used, what you can do in an action, ... the easiest way to find the widget for example is the API. The API doc should be more verbose, providing examples and basic usage of the class. A very good documentation for me is the Qt one, you've got all what you want in one place (Overview, basic code sample, some link to examples, and API doc). See http://doc.trolltech.com/4.5/qthread.html for example. You've got a detailed description with the "More ..." link ( The QThread class provides platform-independent threads. More... ) and in this description there are basic usage, description, samples and then the full API. For a developper (especially an OOP one), the best entry to a documentation is in my opinion the class name. You have the class, you want to know what you can do with it. My 2cts, -- Vincent Jousse http://www.devorigin.fr Le 28/09/09 17:03, Lee Bolding a écrit : > You're all forgetting about http://snippets.symfony-project.org/ which > has all of these features already. > > All that needs to be done is to place a ('show me examples') link at > the bottom of each manual page which links to snippets and displays > snippets tagged with the class or function you're looking at. > > EG > http://snippets.symfony-project.org/snippets/tagged/<class>/order_by/date > > No need to overcomplicate things or re-invent the wheel. That wouldn't > be the Symfony way, would it? ;) > > On 28 Sep 2009, at 15:32, Bruno Reis wrote: > >> For me, there is one major reason for the popularity and spread of >> the php in the word: comments on the manual pages! Nobody can make a >> documentation as good as the whole comunity can make together. There >> is allways a different point of view, way of teaching and learning a >> specific subject. Thats the fortune of the php manual. Of course you >> have to filter a lot of things, but filtering is a essential skill to >> someone looking to learn the best way to do his job. >> >> Put comments on the manual and you will see.... >> >> >> 2009/9/28 Gareth McCumskey <gmccums...@gmail.com >> <mailto:gmccums...@gmail.com>> >> >> I was actually thinking, when I menioned the comments sections on >> php.net <http://php.net/>, about the snippets section. It would >> be great to link to that to give a nice easily understandable >> example of usage. >> >> We do have the various books and these are great but the >> comments/snippets sections are great for looking up how to do >> those slightly more obscure/intricate things with the framework >> that wouldn't be found in the official books. >> >> >> On Mon, Sep 28, 2009 at 4:03 PM, eMerzh <merz...@gmail.com >> <mailto:merz...@gmail.com>> wrote: >> >> Why not integrate the api with the snipped page... or smth >> like this... >> It's a real happiness for a beginner to have a lot of >> exemples... and taht all the example can be found in a >> central place... >> >> or the comment could have some rating system... >> >> >> On Mon, Sep 28, 2009 at 15:28, Fabian Lange >> <fabian.la...@symfony-project.com >> <mailto:fabian.la...@symfony-project.com>> wrote: >> >> >> I personally dislike the php.net <http://php.net/> api >> comments >> they are full of junk. >> the solutions are untested, undocumented, not working or >> messy. >> Fabian >> >> >> >> >> >> >> >> >> -- >> Gareth McCumskey >> http://garethmccumskey.blogspot.com >> <http://garethmccumskey.blogspot.com/> >> twitter: @garethmcc >> >> >> >> >> > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "symfony users" group. To post to this group, send email to symfony-users@googlegroups.com To unsubscribe from this group, send email to symfony-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/symfony-users?hl=en -~----------~----~----~----~------~----~------~--~---
