2011/1/11 Gaetano Giunta <giunta.gaet...@gmail.com> > Maxime Thomas wrote: > >> Hi, >> >> As started on Twitter with @arno_u_loginlux, we think that the ezc / azc >> documentation can be improved in several ways. >> >> As an end-user of this library / framework, I like the spirit of it and >> the >> way you can quickly adopt a component and use it in your software. >> >> However, regarding the documentation, for more than one year that I'm >> using >> mostly all components and I think we can complete it / improve it. >> >> I list here my thoughts about the documentation and you may feel free to >> add >> or challenge each point. In my opinion, each component have to get the >> following piece of information (if it hasn't yet) : >> >> - a schema : a visual way to understand the concepts underneath. We get >> it one for MVC which was cool because it's I guess the most complex one >> but >> I think it's not enough. >> - a list of examples, which can be like the PHP documentation, user >> contributed. The aim is to provide example of the real life or specific >> use >> that are not specified in the built-in specification. >> - a method that can be used to easily debug the code. Typical dev does >> not want to get in the ezc code but just use it. It's a bit problematic >> to >> know if there's a real bug inside the component or if it's a bad usage >> we >> are making of it. For example, I use PersistentObject and I would like >> to >> know why the find query returns me nothing. In the documentation, >> there's no >> clue to that could help me to resolve my probleme. And also, there's no >> way >> to print the $q->getQuery() without hacking PersistentObject. Maybe we >> must >> consider the fact to create a false dependancy to Debug, disabled by >> default. >> > That's a tough problem, but I concur with the last point. > > To me, the way the components work often feels like blackmagick: sometimes > it is logical, but more often it's just like incantations. The example > spells given in the docs are fine, but as soon as you stray a little bit > from those, you're on your own - either it works at the very first try or it > becomes a thankless test/change/repeat loop (eg. sometimes a certain mix of > options work, and another mix does not work, or some methods have to be > invoked in a particular order). > As far as I can tell, this is at least in part a fruit of the > design/architecture of the components: with the division of tasks in so many > small classes and the heavy usage of subclasses and magic methods (getters, > setters etc), following the logic trough the code is not the easiest task. > The upside being that more often than not, you will be able to solve your > problem by creating a subclass with a one-liner fix in a single method! > > I have no real proposal to make for debugging helpers, but am interested in > any that might be given... > > bye > Gaetano > > By resolving this, I guess we will increase the number of user. >> I know that it is a significant effort on documentation but it will have a >> great effect on users. >> >> > The first point was just to document those solutions which can help you debugging what you've done. Of course, we can use inheritance, but it can be a problem for some classes that check the class type (instance of). Maybe we can just list what we want to debug then think to a mechanism. My first think goes to everything which can query (Db, LDAP, Search and so on).
-- Maxime maxime.tho...@wascou.org | www.wascou.org | http://twitter.com/wascou
