Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

eZ Publish 4.3+ Template compatibility and documentation improvements #1

Closed

Conversation

brookinsconsulting
Copy link

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

Cheers,
Brookins Consulting

…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
@@ -0,0 +1,15 @@
Copyright (C) 2010 - 2012 A.Bakkeboe.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this file needed? Try not to repeat documentation information over multiple files, that just makes it harder to update.

I would also remove the same information from the README.md file, having a doc/LICENSE file should cover the needs here.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We at BC have patterns we apply to extension copyright documentation. One of them is the existence of a clear copyright assignment file with clear documentation on the license of the copywritten works, outside of the ezinfo and extension.xml standards. This file provides for both of these concerns very well for other projects, we think each extension should have one.

We think having doc/LICENSE is simply not enough as that is mearly license distribution not assignment, though again these are BC standards. A README.md is often considered enough but we believe it is better to be more clear than enough.

Duplication here is minimal and would change very infrequently.

@arnebratt
Copy link
Owner

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.

@brookinsconsulting
Copy link
Author

Thank you for your review and feedback. I will try to refactor the changes further and submit more changes soon based on your feedback.

@brookinsconsulting
Copy link
Author

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.

Hello!

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:

/**

  • Comment about the next code block
    */

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.

Respectfully,
Brookins Consulting

@brookinsconsulting
Copy link
Author

Since this extension pull request was not understood, accepted or welcomed it has now been closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants