Merge pull request #56 from Crell/formatting-cleanup

Assorted formatting and wording cleanup.

Author: KorvinSzanto

spec.md

@@ -131,7 +131,7 @@ Short form of type keywords MUST be used i.e. `bool` instead of `boolean`,
 ### 2.6 Trailing commas
 
 Numerous PHP constructs allow a sequence of values to be separated by a comma,
-and the final item may have an optional comma.  Examples include array key/value pairs,
+and the final item may have an optional comma. Examples include array key/value pairs,
 function arguments, closure `use` statements, `match()` statement branches, etc.
 
 If that list is contained on a single line, then the last item MUST NOT have a trailing comma.
@@ -279,6 +279,7 @@ Declare statements MUST NOT contain any spaces and MUST be exactly `declare(stri
 
 Block declare statements are allowed and MUST be formatted as below. Note position of
 braces and spacing:
+
 ```php
 declare(ticks=1) {
     // some code
@@ -293,15 +294,15 @@ Any closing brace MUST NOT be followed by any comment or statement on the
 same line.
 
 When instantiating a new class, parentheses MUST always be present even when
-there are no arguments passed to the constructor.
+there are no arguments passed to the constructor. For example:
 
 ```php
 new Foo();
 ```
 
 If class contains no additional declarations (such as an exception that exists only extend another exception with a new type),
 then the body of the class SHOULD be abbreviated as `{}` and placed on the same line as the previous symbol,
-separated by a space.  For example:
+separated by a space. For example:
 
 ```php
 class MyException extends \RuntimeException {}
@@ -312,15 +313,13 @@ class MyException extends \RuntimeException {}
 The `extends` and `implements` keywords MUST be declared on the same line as
 the class name.
 
-The opening brace for the class MUST go on its own line; the closing brace
-for the class MUST go on the next line after the body.
-
-Opening braces MUST be on their own line and MUST NOT be preceded or followed
-by a blank line.
+The opening brace for the class MUST go on its own line, and MUST NOT be
+preceded or followed by a blank line.
 
-Closing braces MUST be on their own line and MUST NOT be preceded by a blank
-line.
+The closing brace for the class MUST go on its own line, immediately following
+the last line of the class body, and MUST NOT be preceded by a blank line.
 
+The following is a validly formatted class:
 
 ```php
 <?php
@@ -340,7 +339,7 @@ class ClassName extends ParentClass implements \ArrayAccess, \Countable
 Lists of `implements` and, in the case of interfaces, `extends` MAY be split
 across multiple lines, where each subsequent line is indented once. When doing
 so, the first item in the list MUST be on the next line, and there MUST be only
-one interface per line.
+one interface per line. For example:
 
 ```php
 <?php
@@ -365,22 +364,11 @@ class ClassName extends ParentClass implements
 The `use` keyword used inside the classes to implement traits MUST be
 declared on the next line after the opening brace.
 
-```php
-<?php
-
-namespace Vendor\Package;
-
-use Vendor\Package\FirstTrait;
-
-class ClassName
-{
-    use FirstTrait;
-}
-```
-
 Each individual trait that is imported into a class MUST be included
 one-per-line and each inclusion MUST have its own `use` import statement.
 
+The following is a correct example of trait usage.
+
 ```php
 <?php
 
@@ -400,6 +388,7 @@ class ClassName
 
 When the class has nothing after the `use` import statement, the class
 closing brace MUST be on the next line after the `use` import statement.
+For example:
 
 ```php
 <?php
@@ -414,7 +403,7 @@ class ClassName
 }
 ```
 
-Otherwise, it MUST have a blank line after the `use` import statement.
+Otherwise, it MUST have a blank line after the `use` import statement, as in:
 
 ```php
 <?php
@@ -431,7 +420,7 @@ class ClassName
 }
 ```
 
-When using the `insteadof` and `as` operators they must be used as follows taking
+When using the `insteadof` and `as` operators they MUST be used as follows taking
 note of indentation, spacing, and new lines.
 
 ```php
@@ -525,7 +514,7 @@ function fooBarBaz($arg1, &$arg2, $arg3 = [])
 
 If a function or method contains no statements (such as a no-op implementation or when using
 constructor property promotion), then the body SHOULD be abbreviated as `{}` and placed on the same
-line as the previous symbol, separated by a space.  For example:
+line as the previous symbol, separated by a space. For example:
 
 ```php
 class Point
@@ -552,7 +541,7 @@ In the argument list, there MUST NOT be a space before each comma, and there
 MUST be one space after each comma.
 
 Method and function parameters with default values MUST go at the end of the argument
-list.
+list. For example:
 
 ```php
 <?php
@@ -574,7 +563,7 @@ next line, and there MUST be only one argument per line.
 
 When the argument list is split across multiple lines, the closing parenthesis
 and opening brace MUST be placed together on their own line with one space
-between them.
+between them. For example:
 
 ```php
 <?php
@@ -596,7 +585,7 @@ class ClassName
 When you have a return type declaration present, there MUST be one space after
 the colon followed by the type declaration. The colon and declaration MUST be
 on the same line as the argument list closing parenthesis with no spaces between
-the two characters.
+the two characters. For example:
 
 ```php
 <?php
@@ -623,7 +612,7 @@ class ReturnTypeVariations
 ```
 
 In nullable type declarations, there MUST NOT be a space between the question mark
-and the type.
+and the type. For example:
 
 ```php
 <?php
@@ -667,7 +656,7 @@ public function process(string $algorithm, &...$parts)
 ### 4.6 Modifier Keywords
 
 Classes, properties, and methods have numerous keyword modifiers that alter how the
-engine and language handles them.  When present, they MUST be in the following order:
+engine and language handles them. When present, they MUST be in the following order:
 
 * Inheritance modifier: `abstract` or `final`
 * Visibility modifier: `public`, `protected`, or `private`
@@ -678,6 +667,8 @@ engine and language handles them.  When present, they MUST be in the following o
 
 All keywords MUST be on a single line, and MUST be separated by a single space.
 
+The following is a correct example of modifier keyword usage:
+
 ```php
 <?php
 
@@ -711,6 +702,8 @@ after the opening parenthesis, and there MUST NOT be a space before the
 closing parenthesis. In the argument list, there MUST NOT be a space before
 each comma, and there MUST be one space after each comma.
 
+The following lines show correct calls:
+
 ```php
 <?php
 
@@ -725,6 +718,8 @@ next line, and there MUST be only one argument per line. A single argument being
 split across multiple lines (as might be the case with an anonymous function or
 array) does not constitute splitting the argument list itself.
 
+The following examples show correct argument usage.
+
 ```php
 <?php
 
@@ -748,14 +743,14 @@ $app->get('/hello/{name}', function ($name) use ($app) {
 ```
 
 If using named arguments, there MUST NOT be a space between the argument name
-and colon, and there MUST be a single space between the colon and the argument value.
+and colon, and there MUST be a single space between the colon and the argument value. For example:
 
 ```php
 somefunction($a, b: $b, c: 'c');
 ```
 
 Method chaining MAY be put on separate lines, where each subsequent line is indented once. When doing so, the first
-method MUST be on the next line.
+method MUST be on the next line. For example:
 
 ```php
 $someInstance
@@ -768,7 +763,7 @@ $someInstance
 
 A function or method may be referenced in a way that creates a closure out of it, by providing `...` in place of arguments.
 
-If so, the `...` MUST NOT include any whitespace before or after.  That is, the correct format is `foo(...)`.
+If so, the `...` MUST NOT include any whitespace before or after. That is, the correct format is `foo(...)`.
 
 ## 5. Control Structures
 
@@ -815,6 +810,8 @@ placed together on their own line with one space between them. Boolean
 operators between conditions MUST always be at the beginning or at the end of
 the line, not a mix of both.
 
+For example:
+
 ```php
 <?php
 
@@ -867,6 +864,8 @@ placed together on their own line with one space between them. Boolean
 operators between conditions MUST always be at the beginning or at the end of
 the line, not a mix of both.
 
+For example:
+
 ```php
 <?php
 
@@ -936,7 +935,7 @@ do {
 Expressions in parentheses MAY be split across multiple lines, where each
 subsequent line is indented at least once. When doing so, the first condition
 MUST be on the next line. Boolean operators between conditions MUST
-always be at the beginning or at the end of the line, not a mix of both.
+always be at the beginning or at the end of the line, not a mix of both. For example:
 
 ```php
 <?php
@@ -965,7 +964,7 @@ for ($i = 0; $i < 10; $i++) {
 Expressions in parentheses MAY be split across multiple lines, where each
 subsequent line is indented at least once. When doing so, the first expression
 MUST be on the next line. The closing parenthesis and opening brace MUST be
-placed together on their own line with one space between them.
+placed together on their own line with one space between them. For example:
 
 ```php
 <?php
@@ -1023,7 +1022,7 @@ All operators not described here are left undefined.
 ### 6.1. Unary operators
 
 The increment/decrement operators MUST NOT have any space between
-the operator and operand.
+the operator and operand:
 
 ```php
 $i++;
@@ -1063,6 +1062,7 @@ $variable = $foo ? 'foo' : 'bar';
 
 When the middle operand of the conditional operator is omitted, the operator
 MUST follow the same style rules as other binary [comparison][] operators:
+
 ```php
 $variable = $foo ?: 'bar';
 ```
@@ -1194,7 +1194,7 @@ The `=>` symbol MUST be preceded and succeeded by a space.
 
 The semicolon at the end of the expression MUST NOT be preceded by a space.
 
-The expression portion MAY be split to a subsequent line.  If so, the `=>` MUST be included
+The expression portion MAY be split to a subsequent line. If so, the `=>` MUST be included
 on the second line, and MUST be indented once.
 
 The following examples show proper common usage of short closures.
@@ -1231,7 +1231,7 @@ the list of `implements` interfaces does not wrap. If the list of interfaces
 wraps, the brace MUST be placed on the line immediately following the last
 interface.
 
-If the anonymous class has no arguments, the `()` after `class` MUST be omitted.
+If the anonymous class has no arguments, the `()` after `class` MUST be omitted. For example:
 
 ```php
 <?php
@@ -1260,17 +1260,19 @@ $instance = new class($a) extends \Foo implements
 
 Enumerations (enums) MUST follow the same guidelines as classes, except where otherwise noted below.
 
-Methods in enums MUST follow the same guidelines as methods in classes.  Non-public methods MUST use `private`
+Methods in enums MUST follow the same guidelines as methods in classes. Non-public methods MUST use `private`
 instead of `protected`, as enums do not support inheritance.
 
 When using a backed enum, there MUST NOT be a space between the enum name and colon, and there MUST be exactly one
-space between the colon and the backing type.  This is consistent with the style for return types.
+space between the colon and the backing type. This is consistent with the style for return types.
 
-Enum case declarations MUST use PascalCase capitalization.  Enum case declarations MUST be on their own line.
+Enum case declarations MUST use PascalCase capitalization. Enum case declarations MUST be on their own line.
 
 Constants in Enumerations MAY use either PascalCase or UPPER_CASE capitalization. PascalCase is RECOMMENDED,
 so that it is consistent with case declarations.
 
+The following example shows a typical valid Enum:
+
 ```php
 enum Suit: string
 {
@@ -1296,6 +1298,7 @@ indentation they are declared in.
 
 The following is ***not allowed*** due to the heredoc beginning on a
 different line than the context it's being declared in:
+
 ```php
 $notAllowed =
 <<<'COUNTEREXAMPLE'
@@ -1306,11 +1309,12 @@ $notAllowed =
     COUNTEREXAMPLE;
 ```
 
-Instead the heredoc MUST be declared on the same line as the variable
+Instead, the heredoc MUST be declared on the same line as the variable
 declaration it's being set against.
 
 The follow is ***not allowed*** due to the scope indention not matching the scope the
 heredoc is declared in:
+
 ```php
 function notAllowed()
 {
@@ -1328,6 +1332,7 @@ it's declared in.
 
 The following is an example of both a heredoc and a nowdoc declared in a
 compliant way:
+
 ```php
 function allowed()
 {
@@ -1383,6 +1388,8 @@ MUST be placed on the next line after the last value. There MUST NOT be more
 than one value assignment per line. Value assignments MAY use a single line
 or multiple lines.
 
+The following example shows correct array usage:
+
 ```php
 <?php
 
@@ -1421,12 +1428,12 @@ be placed on their own line, immediately prior to the structure being described.
 For attributes on parameters, if the parameter list is presented on a single line,
 the attribute MUST be placed inline with the parameter it describes, separated by a single space.
 If the parameter list is split into multiple lines for any reason, the attribute MUST be placed on
-its own line prior to the parameter, indented the same as the parameter.  If the parameter list
+its own line prior to the parameter, indented the same as the parameter. If the parameter list
 is split into multiple lines, a blank line MAY be included between one parameter and the attributes
 of the following parameter in order to aid readability.
 
 If a comment docblock is present on a structure that also includes an attribute, the comment block MUST
-come first, followed by any attributes, followed by the structure itself.  There MUST NOT be any blank lines
+come first, followed by any attributes, followed by the structure itself. There MUST NOT be any blank lines
 between the docblock and attributes, or the attributes and the structure.
 
 If two separate attribute blocks are used in a multi-line context, they MUST be on separate lines with no blank
@@ -1435,7 +1442,7 @@ lines between them.
 ### 12.3 Compound attributes
 
 If multiple attributes are placed in the same attribute block, they MUST be separated by a comma with a space
-following but no space preceding.  If the attribute list is split into multiple lines for any reason, then the
+following but no space preceding. If the attribute list is split into multiple lines for any reason, then the
 attributes MUST be placed in separate attribute blocks. Those blocks may themselves contain multiple
 attributes provided this rule is respected.