Merge pull request joomla#47 from Hutchy68/gh-pages

Updates to the Coding Standards Manual

Author: mbabker

assets/css/manual.css

@@ -13,4 +13,47 @@ th
 {
 	border: 1px solid gray;
 	padding: 10px;
+}
+.manual-image {
+	margin: .5em 0 2em 0;
+	text-align: center;
+}
+h1,h2,h3 {
+	line-height:36px;
+}
+h1 {
+	font-size:34.5px;
+}
+h2 {
+	font-size:28.5px;
+}
+h3 {
+	font-size:22.5px;
+}
+h4 {
+	font-size:18.5px;
+}
+h5 {
+	font-size:14px;
+}
+h6 {
+	font-size:11.9px;
+}
+h1 small {
+	font-size:22.5px;
+}
+h2 small {
+	font-size:18.5px;
+}
+h3 small {
+	font-size:14px;
+}
+h4 small {
+	font-size:14px;
+}
+#version {
+	float:right;
+	font-size:.85em;
+	font-weight:bold;
+}
 }

assets/img/joomla_coding_standards_manual.png

@@ -52,6 +52,16 @@ var populateMenu = function() {
 	}).send();
 }
 
+var populateVersion = function() {
+	var versionRequest = new Request({
+		"url": here + 'manual/en-US/version.md',
+		"method": "get",
+		"onSuccess": function(response) {
+			$('version').set('html', marked(response));
+		}
+	}).send();
+}
+
 window.addEvent('domready', function() {
 	var urlParts = document.URL.split('?', 2);
 	state = {};
@@ -63,7 +73,7 @@ window.addEvent('domready', function() {
 	}
 	else
 	{
-		var currentDoc = "chapters/introduction.md";
+		var currentDoc = "coding-standards/introduction.md";
 	}
 
 	marked.setOptions({
@@ -78,6 +88,7 @@ window.addEvent('domready', function() {
 	})
 	populateMenu();
 	populateWindow(currentDoc);
+	populateVersion();
 
 	document.id('main').addEvent('click:relay(a)', function (event, target) {
 		if (target.get('href').substring(0, 4) != 'http' && target.get('href').substring(0, 1) != '#')

assets/js/manual.js

@@ -33,18 +33,21 @@
             <span class="icon-bar"></span>
             <span class="icon-bar"></span>
           </a>
-          <a class="brand" href="#">Joomla! Coding Standards Manual</a>
+          <a class="brand" href="/coding-standards/">Joomla! Coding Standards Manual</a>
         </div>
       </div>
     </div>
 
     <div id="main" class="container-fluid">
       <div class="row-fluid">
         <div class="span3">
+          <div class="manual-image">
+          <img src="assets/img/joomla_coding_standards_manual.png?raw=true" alt="Joomla! Graphic">
+          </div>	
           <div class="well sidebar-nav" id="doc-menu">
           </div><!--/.well -->
         </div><!--/span-->
-        <div class="span9">
+        <div class="span9">	
           <div id="docwin">
           </div>
         </div><!--/span-->
@@ -53,13 +56,17 @@
       <hr>
 
       <footer>
+      	<div class="well">
+      	<h4>License</h4>
         <p>The contents of the Joomla! Coding Standards Manual are subject to copyright law and are made available under the <a href="http://docs.joomla.org/JEDL"
         title="Joomla! Electronic Documentation License (JEDL)">Joomla! Electronic Documentation License (JEDL)</a> unless otherwise stated.
         You may find the <a href="http://docs.joomla.org/JEDL/FAQ" title="JEDL Frequently Asked Questions">JEDL Frequently Asked Questions</a>
         useful in determining if your proposed use of this material is allowed. If you have any questions regarding licensing of this
         material please contact <a href="mailto:legal@opensourcematters.org" title="Email Open Source Matters">legal@opensourcematters.org</a>.
         If you wish to report a possible violation of the license terms for the material on this site then please contact
         <a href="mailto:legal@opensourcematters.org" title="Email Open Source Matters">legal@opensourcematters.org</a>.</p>
+        </div>
+        <div id="version"></div>      
       </footer>
 
     </div><!--/.fluid-container-->

index.html

@@ -1,33 +1,37 @@
-### Configuring Code Analysis Tools
+## Coding Standards Analysis
 
-#### Coding Standards Analysis
+For new contributions we are going to be enforcing coding standards to ensure that the coding style in the source code is consistent. Ensuring that your code meets these standards will make the process of code contribution smoother.
 
-In order to improve the consistency and readability of the source code,
-we run a coding style analysis tool everytime changes are pushed in the
-repo. For new contributions we are going to be enforcing coding
-standards to ensure that the coding style in the source code is
-consistent. Ensuring that your code meets these standards will make the
-process of code contribution smoother.
+## Configuring Code Analysis Tools
 
-The Joomla Platform sniffer rules are written to be used with a tool
-called PHP\_CodeSniffer. Please see the [PHP\_CodeSniffer Pear
+In order to improve the consistency and readability of the source code, the Joomla project runs a coding style analysis tool, CodeSniffer, everytime changes are pushed to a Joomla project's repository. 
+
+### Running CodeSniffer
+
+The Joomla Coding Standards sniffer rules are written to be used with a tool called PHP CodeSniffer. Please see the [PHP CodeSniffer Pear
 Page](http://pear.php.net/package/PHP_CodeSniffer) for information on
-installing PHP\_CodeSniffer on your system.
+installing PHP CodeSniffer on your system.
 
-##### Running CodeSniffer
+You can run the CodeSniffer by going to the CMS, Framework, or Issue Tracker's root directory and executing 
 
-You can run the CodeSniffer by going to the platform root directory and
-executing `phpcs --report=checkstyle
-      --report-file=build/logs/checkstyle.xml --standard=/path/to/platform/build/phpcs/Joomla /path/to/platform`
+```
+phpcs --report=checkstyle --report-file=build/logs/checkstyle.xml --standard=/path/to/<your root>/build/phpcs/Joomla /path/to/<your root>
+```
 
-Alternatively, if you have Ant installed on your system, you may run the
-CodeSniffer by going to the platform root directory and executing
-`ant phpcs`
+Alternatively, if you have Ant installed on your system, you may run the CodeSniffer by going to the `<root directory>` of the Joomla project's code you want to test and executing
 
-##### Known Issues
+```
+ant phpcs
+```
+
+#### Known Issues
 
 -   There is currently an issue with running the Code Sniffer on the
     Simplepie library. Pointing the sniffs at the libraries/joomla
     directory or below will avoid the issue.
 
+## Other Tools
+
+Here are some other tools available to developers who are planning to submit source code to the project.
 
+### PhpStorm Code Style Scheme

manual/en-US/appendices/analysis.md

@@ -0,0 +1 @@
+## Code Examples

manual/en-US/appendices/examples.md

@@ -1,20 +1,28 @@
 ## Basic Guidelines
 
-This chapter outlines the basic guidelines that cover and files.
+This chapter outlines the basic guidelines covering files contributed to the Joomla project. The most important rule to remember when coding for the Joomla project, **if in doubt, please ask**. 
 
-## File Format
+### File Format
 
-All files contributed to Joomla must be stored as ASCII text, use UTF-8 character encoding and be Unix formatted. Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
+All files contributed to Joomla must be: 
 
-## Spelling
+* Stored as ASCII text
+* Use UTF-8 character encoding
+* Be Unix formatted following these rules. 
+	1. Lines must end only with a line feed (LF). 
+	2. Line feeds are represented as ordinal 10, octal 012 and hex 0A. 
+	3. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
 
-The spelling of words and terms used in code comments and in the naming of class, functions, variables and constant should generally be in accordance with British English rules (en\_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API or other established conventions such as for “color” where is it common practice to maintain US English spelling.
+### Spelling
 
-## Indenting
+The spelling of words and terms used in code comments and in the naming of class, functions, variables and constant should generally be in accordance with British English rules (en\_GB). 
+Some exceptions are permitted, for example where common programming names are used that align with the PHP API or other established conventions such as for `color` where is it common practice to maintain US English spelling.
+
+### Indenting
 
 Tabs are used for indenting code (not spaces as required by the PEAR standard). Source code editors or Integrated Development Environments (IDE’s) such as Eclipse must have the tab-stops for indenting measuring four (4) spaces in length.
 
-## Line Length
+### Line Length
 
 There is no maximum limit for line lengths in files, however, a notional value of about 150 characters is recommended to achieve a good level of readability without horizontal scrolling. Longer lines are permitted if the nature of the code for individual lines requires it and line breaks would have an adverse affect on the final output (such as for mixed PHP/HTML layout files).
 

manual/en-US/coding-standards/chapters/basic-guidelines.md

@@ -0,0 +1,3 @@
+## DocBlocks
+
+@TODO - Entend information about DocBlocks specific to the Framework and CMS. Other project?

manual/en-US/coding-standards/chapters/docblocks.md

@@ -1,14 +1,14 @@
-## Comments
+## Inline Code Comments
 
-This chapter covers inline commenting in more detail. Inline comments are all comments not included in doc blocs. The goal of in line commenting is to explain code in context. Such explanation may take many different forms.
+This chapter covers inline code commenting in more detail. Inline comments are all comments not included in doc blocs. The goal of in line commenting is to explain code in context. Such explanation may take many different forms.
 
 Comments that are written in a readable and narrative style, especially when explaining a complex process, are encouraged. In general they should be placed close to the code explained rather than before the entire block of code.
 
 Comments should be as sentence like as possible, which is to say that they should be complete and readable, not in short hand.
 
 Comments are not a replacement for detailed doc blocks. Comments serve to explain the logic and structure of code itself rather than the use of code.
 
-## Formatting of Comments
+### Formatting of Comments
 
 Comment blocks that introduce large sections of code and are more than 2 lines long should use `/* */` (C) style and should use `*` on each line with the same space/tab rules as doc blocks. If you need a large introduction consider whether this block should be separated into a method to reduce complexity and therefore providing a full docblock.
 
@@ -22,7 +22,7 @@ Comments should align with the code they refer to, using the same indenting as t
 
 Comments should be indented with tabs (like code, not like doc blocks).
 
-## Content of comments
+### Content of comments
 
 Comments should use en-GB (See below).
 
@@ -46,23 +46,23 @@ Comments may include forward looking statements of how something will be extende
 
 Remember that humor and sarcasm are difficult to translate.
 
-## Acronyms
+### Acronyms
 
 Capitalise all letters of acronyms such as HTML, XML, SQL, GMT, and UTC. This is an exception to the general use of en-GB rules.
 
-## Common spelling and grammar errors for which to check.
+### Common spelling and grammar errors for which to check.
 
 Joomla contributors include many non-native speakers of en-GB which makes it understandable that there are sometimes spelling and grammar errors. At the same time, some people reading comments also are non native speakers and may even use automated translation to understand comments. This makes it very important that comments should follow proper en-GB spelling and grammar rules. Unfortunately, these can be tricky.
 
-Wikipedia provides a good summary of common differences between en-US and en-GB. http://en.wikipedia.org/wiki/American\_and\_British\_English\_spelling\_differences Note that there are some instances where en-GB common usage (but not actual rules) varies slightly from en-AU and using en-AU is considered acceptable.
+Wikipedia provides a good summary of [common differences between en-US and en-GB](http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences). Note that there are some instances where en-GB common usage (but not actual rules) varies slightly from en-AU and using en-AU is considered acceptable.
 
-### S vs Z
+#### S vs Z
 
 en-GB most commonly uses `ise` where en-US would use `ize`, such as `normalise` instead of `normalize`. (Note that there are some exceptions to this rule and some differences between en-GB and en-AU in common usage.)
 
 Use of apostrophes is one of the trickier parts of English.
 
-### Lets versus let’s
+#### Lets versus let’s
 
 Lets means permits or allows to:
 
@@ -76,7 +76,7 @@ Let’s is a contraction for let us and means we are going to do this now:
 // Let's validate the field
 ```
 
-### Its versus it’s
+#### Its versus it’s
 
 Its is the possessive form of it:
 
@@ -90,8 +90,8 @@ It’s is a contraction of it is
 // It's time to save
 ```
 
-### The correct Joomla spelling of some commonly used words.
-
--   Dependant
+#### The correct Joomla spelling of some commonly used words.
 
+-   dependant
+-	deprecated
 

manual/en-US/coding-standards/chapters/comments.md renamed to manual/en-US/coding-standards/chapters/inline-comments.md

@@ -173,6 +173,8 @@ For example, do not include feature submissions like:
 //$code = broken($fixme);
 ```
 
+More details on inline code comments can be found in the chapter on [Inline Code Comments](coding-standards/chapters/inline-comments.md).
+
 ### Comment Docblocks
 
 Documentation headers for PHP and Javascript code in files, classes, class properties, methods and functions, called the docblocks, follow a convention similar to JavaDoc or phpDOC.