I do NOT see comments on the cakephp documentation to be valuable. I think comments like php.net are great when your talking about how to use a function. Most of the content of the cakephp book is how to use the framework a little bit more extensive than a sequence of function calls. This is where comments really don't help, the comments are either not complete enough to really help anyone or they are misleading and end up confusing more than they help.
Examples of use with decent explanations are extremely valuable, and should be made part of the documentation, and I think the authors of the book have been doing a great job at this in recent years. These examples tend to take more effort to put together. Submitted to git where the concepts can also be reviewed by the architects of the framework and verified against best practice. Best practice is another issue when you step past the function to the framework. A lot of the comments go against best practice because it takes to much effort to explain how to do it correctly in a comment. This is why we see way too much code in the controller that should be in the model. I'm pretty sure for the most part we can all read an API for a function. There are plenty of comments on usage of specific functions and parameters in the google groups. A good number with links back to the documentation. If you really want to see how to use a function take a peek at the test case. The documentation needs more real examples that focus on solving a specific problem, or best practice on using a specific part of the framework. This is where we can really add to the value of the documentation. Another problem with comments is when you go to convert or output your documentation in different formats like PDF etc. You generally don't get the comments which might show one or two good examples, or you get all the comments regardless of how relevant they might be. I vote for using a tool like sphinx for documentation. Using git and community contributed commits to enhance the documentation. And I vote for keeping comments and questions in the groups, IRC channels and personal Blog space. I really appreciate all the efforts the Core team has put into this project. They have made the work I do more enjoyable, and less tedious. Keep up the great work! -- Our newest site for the community: CakePHP Video Tutorials http://tv.cakephp.org Check out the new CakePHP Questions site http://ask.cakephp.org and help others with their CakePHP related questions. To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/cake-php
