Re: [PATCH v4] docs: dt-bindings: Specify ordering for properties within groups

["Rob Herring (Arm)" <robh@kernel.org>]

On Fri, 21 Mar 2025 05:57:09 +0100, Dragan Simic wrote:
> 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>
> ---
> 
> Notes:
>     Changes in v4:
>       - Compacted both the introduced additions to the DTS conding style
>         and the patch description, as suggested by Krzysztof [7]
>       - Reformatted the patch description to obey the 75-column-width
>         rule, and adjusted the editor configuration accordingly, to avoid
>         such issues in the future, as suggested by Krzysztof [7]
> 
>     Changes in v3:
>       - Rewrote the part of the changes that describes natural sort order
>         and its relation to "standard" alpha-numerical ordering, to make
>         it more understandable, as suggested by Krzysztof [6]
>       - Slightly expanded the patch description, to clarify the additional
>         goal of explaining the natural sort order briefly
> 
>     Changes in v2:
>       - Changed the additions to the coding style to specify natural sort
>         order, which avoids amibguity, as suggested by Krzysztof [5]
>       - Adjusted and expanded the patch description appropriately, together
>         with including one more reference for the natural sort order
> 
>     Link to v1: https://lore.kernel.org/linux-kernel/09d6f2fc111b3d6e58987336944f93ec36b65118.1741071107.git.dsimic@manjaro.org/T/#u
>     Link to v2: https://lore.kernel.org/linux-kernel/47c51c10098f089e52fb14c5c5527611dc8daf32.1741164239.git.dsimic@manjaro.org/T/#u
>     Link to v3: https://lore.kernel.org/linux-kernel/7276139ea1f4a5f4db48c77f536a3638492e6c2f.1741321984.git.dsimic@manjaro.org/T/#u
> 
>     [5] https://lore.kernel.org/linux-kernel/20250305-defiant-serious-newt-b7c5ea@krzk-bin/
>     [6] https://lore.kernel.org/linux-kernel/20250306-dexterous-goshawk-of-aptitude-e4f1f6@krzk-bin/
>     [7] https://lore.kernel.org/linux-kernel/20250307-logical-nimble-okapi-3ba081@krzk-bin/
> 
>  Documentation/devicetree/bindings/dts-coding-style.rst | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)
> 

Applied, thanks!