eZ Publish 4.3+ Template compatibility and documentation improvements #1
This pull request consists of 3 simple commits to the documentation, settings and module view php files.
The pull request provides enhanced documentation in GitHub markup (The new favorite), utf8 settings formatting consistency and module view php source code comment enhancements.
These enhancements make the code better and new user documentation more friendly.
Thank you for your continued support
…ganized extension documentation. Added copy of the license.
…ctory to be compatible with ez 4.3+ (4.4/4.7/CB2012.02). Added phpdoc comment block documentation and copyright attribution
In general I agree with the changes here. I would be more carefull with commenting everything though, adding a comment for every line on simple tasks like the template factory for instance just makes a lot more source code and gives no added documentation value. This goes double when you use three lines for every comment instead of one.
In response to your comment after some thought a number of things come to mind.
BC Standards have long insisted that code with verbose comments that explain to all developers regardless of experience just what is happening as much as possible are much better than code without such verbose comments.
Also BC Standards have recently been improved to ensure that while lower level implementations of our standards (which did provide for a // comment standard) are still supported, they are discouraged in favor for the more recently popular comment block style comments:
Please try to understand. Your users will respect the care we have taken to ensure the code is prepared for even more improved code block comment text if the current simpler text is not quite enough because their modified versions will be simpler to change the comments to meet their own code documentation needs simply by using code which provides for such blocks by default.
Providing for standard code block documentation, even simple or trivial documentation increases code value especially when the code's very use will always be in such a way that the additional length of the code in question is virtually trivially negated with the value provided (re: inline code documentation blocks) in exchange for said length of code. Also the longer code block standard is also similar to the more recent / popular / preferred documentation standard known as PHPDoc.
Please let us know how these replies find you.