Document DocBlockTagOrder configuration

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.