Document DocBlockTagOrder configuration (#61)

* Document DocBlockTagOrder configuration

Add a docs/README.md section covering the three public properties of
PhpCollective.Commenting.DocBlockTagOrder: order (function/method
docblocks), classOrder (class/interface/trait docblocks), and
innerOrder (within-bucket ordering with prefix patterns). These were
only discoverable by reading the sniff source.

Includes both common innerOrder recipes (CRUD method ordering plus
alphabetized property lists), notes the asymmetric handling of the
leading at-sign on tag names between order/classOrder and innerOrder
keys, and explains the InnerOrderInvalid error code as a scoping
lever for keeping inner ordering on tables/views/controllers while
skipping entity docblocks where DB-schema order is meaningful.

* Update README.md

Author: dereuromark

docs/README.md

@@ -98,6 +98,65 @@ To enable checking for (and auto-fixing) invalid `: void` return types on these
     </rule>
 ```
 
+## Customize DocBlock tag ordering
+`PhpCollective.Commenting.DocBlockTagOrder` enforces a consistent tag order in docblocks for functions, methods, classes, interfaces, and traits. Three properties can be overridden via XML.
+
+### Function/method docblock order
+Default: `deprecated`, `see`, `param`, `throws`, `return`. Tags not in the list keep their relative position above the listed ones. The leading `@` on tag names is optional and gets normalized.
+```xml
+    <rule ref="PhpCollective.Commenting.DocBlockTagOrder">
+        <properties>
+            <property name="order" type="array" value="deprecated,see,param,throws,return"/>
+        </properties>
+    </rule>
+```
+
+### Class/interface/trait docblock order
+Default: `template`, `extends`, `implements`, `property`, `property-read`, `property-write`, `method`, `mixin`. Independent of `order` so function and class docblocks can be tuned separately.
+```xml
+    <rule ref="PhpCollective.Commenting.DocBlockTagOrder">
+        <properties>
+            <property name="classOrder" type="array" value="extends,property,method,mixin"/>
+        </properties>
+    </rule>
+```
+
+### Inner (within-bucket) ordering
+Optional. When configured, orders tags *within* a bucket. Only applies to class/interface/trait docblocks - per-method `@param` / `@return` tags are positional and have no within-bucket subject.
+
+Each entry's value is a comma-separated list of prefix patterns. A trailing `*` matches any suffix; a bare pattern matches only the exact subject. Tags matching no pattern float to the bottom of their bucket. Within each score class (matched-by-same-pattern, or all-unmatched), tags are sorted alphabetically by extracted subject.
+
+An empty value means "alphabetize the whole bucket" - the typical recipe for `@property` association lists generated by IDE helpers.
+
+Example covering both recipes (CRUD method order plus alphabetized property lists):
+```xml
+    <rule ref="PhpCollective.Commenting.DocBlockTagOrder">
+        <properties>
+            <property name="innerOrder" type="array">
+                <element key="@method"
+                         value="newEmptyEntity,newEntity,newEntities,get,find*,findOrCreate,patchEntity,patchEntities,save,saveOrFail,saveMany*,delete,deleteOrFail,deleteMany*"/>
+                <element key="@property" value=""/>
+                <element key="@property-read" value=""/>
+                <element key="@property-write" value=""/>
+            </property>
+        </properties>
+    </rule>
+```
+
+Note: `innerOrder` keys are matched literally - the leading `@` is required, unlike for `order` / `classOrder`.
+
+#### Scoping innerOrder out of entity docblocks
+On CakePHP-style entities the property docblocks list columns in DB schema order (id first, logical fields together, timestamps last). That order is meaningful and stays in sync with `cakephp-ide-helper` regeneration. Alphabetizing breaks column groupings (`lat` / `lng` / `location`, `beginning` / `end`, `lft` / `rght`) and creates churn against the IDE helper.
+
+Inner-order violations are emitted under a separate `InnerOrderInvalid` error code so they can be suppressed independently from the bucket-level `OrderInvalid`:
+```xml
+    <rule ref="PhpCollective.Commenting.DocBlockTagOrder.InnerOrderInvalid">
+        <exclude-pattern>*/src/Model/Entity/*</exclude-pattern>
+    </rule>
+```
+
+Tables, views, and controllers still receive inner ordering in the same project.
+
 ## Excluding test related comparison files
 If you want to exclude certain generated (e.g. PHP) files, make sure those are in a `test_files` subfolder to be auto-skipped.
 You can otherwise always create a custom and rather unique folder name and manually exclude it in your PHPCS settings.