Hello, I just released a plugin to get an API help throught the cli. It's a proof-of-concept, so it's very in a pre-alpha state, needs testing and cleanup, but I'm looking for feedback to improve it.
With this plugin, you have to type what you are looking for to get its API doc: $> symfony api:help sfForm $> symfony api:help sfForm::bind $> symfony api:help url_for If you want to test it, checkout the source from the repository : http://svn.symfony-project.com/plugins/sfHelpPlugin/trunk/ What do you think about it? On Fri, Sep 25, 2009 at 7:26 PM, Jake Barnes <lkrub...@geocities.com> wrote: > > > If you have a look at the API, of course you learn that you can pass an > > array of options to the widget constructors. But, if you look just after > > the method definition, ... surprise, all options are described. And this > > is true for all widgets and validators, all of them. > > Thanks, Fabien. It is good to know that things are getting better. I > started using Symfony with version 1.1, when the the new forms > framework was severely under-documented. The 1.2 branch is better > documented, and it seems the documentation keeps getting better all > the time. > > > > > On Sep 25, 2:38 am, Fabien Potencier <fabien.potenc...@symfony- > project.com> wrote: > > zeev, > > > > I can understand that we need to re-organize the documentation, so that > > it is easier to find things, but your example is the worst possible ever. > > > > If you have a look at the API, of course you learn that you can pass an > > array of options to the widget constructors. But, if you look just after > > the method definition, ... surprise, all options are described. And this > > is true for all widgets and validators, all of them. > > > > Just one example for good measure: > > > > http://www.symfony-project.org/api/1_2/sfWidgetFormChoice#method_conf... > > > > Don't want to dive into the API? All widgets and validators are also > > described in the form book (appendices A for widgets and B for > > validators). If I take the same example as above, here is what we > > explain in the book: > > > > http://www.symfony-project.org/forms/1_2/en/A-Widgets#chapter_a_choic... > > > > All options are described in great details, with images to show you how > > they affect the rendering. > > > > Want to keep the reference offline? Just download the PDF: > > > > http://www.symfony-project.org/get/pdf/forms-1.2-en.pdf > > > > Want to read it in Italian, or Japanese. Still possible: > > > > http://www.symfony-project.org/forms/1_2/it/A-Widgets > > > > Can you explain a bit more what is missing here? > > > > I'm all for documentation enhancements and I'm well aware that we can do > > better. But please, be constructive. > > > > If something is missing, and some things are definitely missing, open a > > ticket, explain the issue, submit a patch if possible, and you will > > become part of making symfony better. > > > > If you want to make symfony better, stop complaining and do something > > about it. I'm always looking for people willing to help. > > > > Fabien > > > > -- > > Fabien Potencier > > Sensio CEO - symfony lead developer > > sensiolabs.com | symfony-project.org | fabien.potencier.org > > Tél: +33 1 40 99 80 80 > > > > > > > > zeek wrote: > > > > > Yes, that is a good example. All of the form widgets suffer from the > > > same problem - if you look at the documentation in the API, it teaches > > > you that the second parameter can be an array of options. But what > > > options are allowed in that array? I've looked around and never found > > > documentation on that - instead, one has to look around for the > > > occasional example, or maybe wade through the source code in hopes of > > > an answer. > > > > > On Sep 24, 3:21 am, eMerzh <merz...@gmail.com> wrote: > > >> I Totally agree.. for me the lack of a clear and complete api is the > biggest > > >> pbm of Sf... > > > > >> i have another example : > > >> herehttp:// > www.symfony-project.org/api/1_2/sfTestFunctionalBase#method_ch... > > >> you can find the documentation about checkResponseElement , and his > "option" > > >> parameter... > > >> But what could i set in this options? I'm forced to look at the code > or > > >> so... > > > > >> If there is a technical platform for it wiki or something, i would be > glad > > >> to help the symfony team to write, translate or add examples in the > > >> documentation.... > > > > >> On Thu, Sep 24, 2009 at 04:16, zeek <z...@thesecondroad.org> wrote: > > > > >>> On Sep 23, 8:10 am, fakingfantastic <lakatos.fr...@gmail.com> wrote: > > >>>> I recently had a discussion with Fabien about this topic, and he > > >>>> suggested it would be best if I stage the debate here. > > >>>> Has anyone ever felt like the information they needed to get on > > >>>> Symfony was hard to find? Do you find that the information you need > is > > >>>> very-well documented on the site, but it takes a while to search > for? > > >>>> These are very big issues for me that over the last 6 months of me > > >>>> learning the framework, have made it quite difficult. > > >>> The information is not optimized for fast lookup. It is optimized for > > >>> a beginner who has the time to spend a few weeks working through > > >>> tutorials. For someone with the time to read all the way through the > > >>> tutorials, the amount of information is terrific. But there is > nothing > > >>> likewww.php.net. Often, I need to double check the parameters for a > > >>> PHP function such as date(). So I open a new browser window and I > > >>> type: > > >>>www.php.net/date > > >>> I would love something like that for Symfony. > > >>> And examples are needed. That is something thatwww.php.nethas. The > > >>> Symfony API is here, but there are no examples: > > >>>http://www.symfony-project.org/api/1_2/ > > >>> How does find one's way into a deep object hierarchy? If you just > > >>> click on an object in the API, you get data, but it is gibberish > > >>> unless you know how each piece connects to another. For instance, how > > >>> much do you learn here: > > >>>http://www.symfony-project.org/api/1_2/sfFactoryConfigHandler > > >>> A clickable UML map might be useful. While PHP is oriented toward > > >>> functions and methods, Symfony is fundamentally OOP, so an UML map > > >>> might be more useful that the long lists of functions that one finds > > >>> onwww.php.net. > > > -- Noël GUILBERT http://www.noelguilbert.com/ http://www.sensiolabs.com http://www.symfony-project.com Sensio Labs Tél: +33 1 40 99 80 80 --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
