docs: dt-bindings: Specify ordering for properties within groups

Ordering of the individual properties inside each property group benefits
from applying natural sort order [1] by the property names, because it
results in more logical and more usable property lists, similarly to what's
already the case with the alpha-numerical ordering of the nodes without
unit addresses.

Let's have this clearly specified in the DTS coding style, and let's expand
the provided node example a bit, to actually show the results of applying
natural sort order.

Applying strict alpha-numerical ordering can result in property lists that
are suboptimal from the usability standpoint.  For the provided example,
which stems from a real-world DT, [2][3][4] applying strict alpha-numerical
ordering produces the following undesirable result:

  vdd-0v9-supply = <&board_vreg1>;
  vdd-12v-supply = <&board_vreg3>;
  vdd-1v8-supply = <&board_vreg4>;
  vdd-3v3-supply = <&board_vreg2>;

Having the properties sorted in natural order by their associated voltages
is more logical, more usable, and a bit more consistent.

[1] https://en.wikipedia.org/wiki/Natural_sort_order
[2] https://lore.kernel.org/linux-rockchip/b39cfd7490d8194f053bf3971f13a43472d1769e.1740941097.git.dsimic@manjaro.org/
[3] https://lore.kernel.org/linux-rockchip/174104113599.8946.16805724674396090918.b4-ty@sntech.de/
[4] https://lore.kernel.org/linux-rockchip/757afa87255212dfa5abf4c0e31deb08@manjaro.org/

Signed-off-by: Dragan Simic <dsimic@manjaro.org>
Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Link: https://lore.kernel.org/r/6468619098f94d8acb00de0431c414c5fcfbbdbf.1742532899.git.dsimic@manjaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>

diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst
index 4772ded8a9872754b9c003925c8d938eba704e2e..202acac0507ab113c0d56c0be1421d3f5c3305e0 100644 (file)
--- a/Documentation/devicetree/bindings/dts-coding-style.rst
+++ b/Documentation/devicetree/bindings/dts-coding-style.rst
@@ -133,6 +133,9 @@ The above-described ordering follows this approach:
 3. Status is the last information to annotate that device node is or is not
    finished (board resources are needed).
 
+The individual properties inside each group shall use natural sort order by
+the property name.
+
 Example::
 
        /* SoC DTSI */
@@ -158,7 +161,10 @@ Example::
        /* Board DTS */
 
        &device_node {
-               vdd-supply = <&board_vreg1>;
+               vdd-0v9-supply = <&board_vreg1>;
+               vdd-1v8-supply = <&board_vreg4>;
+               vdd-3v3-supply = <&board_vreg2>;
+               vdd-12v-supply = <&board_vreg3>;
                status = "okay";
        }