Re: [zeta-dev] Documentation
Hi James, On Tue, Jun 7, 2011 at 12:27 PM, James Pic james...@gmail.com wrote: Hello everybody, Kudos to Gavin for setting up my wiki access! Here is the table of contents i propose: https://cwiki.apache.org/confluence/display/ZETACOMP/Tutorial+TOC Any early thoughts you want to share ? I Like :) -- Jérôme Renard http://39web.fr | http://jrenard.info | http://twitter.com/jeromerenard
Re: [zeta-dev] Documentation
Hi Gaetano On Tue, Jan 11, 2011 at 10:15 PM, Gaetano Giunta giunta.gaet...@gmail.com wrote: 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). Looks like a hacker thing :D Isn't that how pretty much all libs, frameworks, and programming languages work in general ? What lib/program/framework does it better than the components and why ? Regards James -- http://jamespic.info Customer is king - Le client est roi - El cliente es rey.
Re: [zeta-dev] Documentation
Hi all, On Wed, Jan 12, 2011 at 8:46 AM, Christian Grobmeier grobme...@gmail.com wrote: - a method that can be used to easily debug the code. ... 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. Isn't it possible by just setting a breakpoint and without hacking ? Maybe we must consider the fact to create a false dependancy to Debug, disabled by default. What would be the benefits of that over xdebug ? I insist for your own good, maybe the source of your problem is not specific to the components... are you sure you're using xdebug correctly ? Regards James -- http://jamespic.info Customer is king - Le client est roi - El cliente es rey.
Re: [zeta-dev] Documentation
On Tue, Jan 11, 2011 at 2:39 PM, Ronan Guilloux ronan.guill...@gmail.comwrote: +1 for all that Maxime wrote about. But my very first need tweet was simpler : How to add a set of cronjobs, and how to add a PhpUnit test suite into a HelloMvc-like website (cf. http://goo.gl/TvXVn) . Adding cronjobs is easy, but this should be documented or shown in an example a day, since it's a common need. Do you mean, how to setup a cronjob and post-commit hooks ? What do you think would be zetacomponents-specific about that ? I'll try to improve my frenchy globish english a write a decent tutorial about that, somehwere, some day. Yeah I know, we French are the worst English speakers in the world :D The main difficult I encountered was to implement PhpUnit easely. Some weeks ago I crawled the all Zeta Components example apps (here : http://goo.gl/Xg828) but I didn't found any app implementing PhpUnit yet. PhpUnit doc about bootstrapping was not clear enough to me. Did you consider Arbit project sources ? It's built upon ZetaComponents and uses PHPUnit for testing. I've uploaded the sources of the last app framework i coded with the components, it uses PHPUnit for testing: https://github.com/jpic/zetamad but reading the UnitTest bootstrap.php file (found here : http://goo.gl/nH96H) helped a lot and it finally did the job. Unfortunatly, while UnitTest is listed in the official Zeta Components docs, it's a broken link in the official doc (here : http://goo.gl/wKHnN). UnitTest barely wraps around PHPUnit, providing a few features that are specific to components tests. Which of its features do you need in your project ? Implemeting PhpUnit into Zeta Components needs a tutorial Did you consider: The tutorial to install PHPUnit: http://www.phpunit.de/manual/current/en/installation.html The tutorial to writing tests: http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html The tutorial automating builds: http://www.phpunit.de/manual/current/en/build-automation.html The tutorial to continuous integration by Arbit: http://tracker.arbitracker.org/arbit/documentation/view/ContinuousIntegration I'd candidate although i'd need your opinion concerning the following questions: - do these tutorial contain the informations you are looking for ? - if not, what other information do you need ? - if so, why, where and how should the components cover these topics ? Regards James -- http://jamespic.info Customer is king - Le client est roi - El cliente es rey.
Re: [zeta-dev] Documentation
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.
Re: [zeta-dev] Documentation
- a method that can be used to easily debug the code. ... 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. I have no real proposal to make for debugging helpers, but am interested in any that might be given... Usually logging systems are being used. In this case log4php could generate warnings if configured. But this would require to depend on log4php. Of course zeta can provide a mock object which does nothing, in case log4php classes can not be found. This also will keep up the speed in production systems Dependency Injection can be used to inject some kind of a logging object. But... how many people are there who can use DI? Plain and simple logging will do the job for most people.
