From 6c269a9edc45f17fba5a59ab96b989831ecbdfb9 Mon Sep 17 00:00:00 2001
From: Keith Short <keithshort@google.com>
Date: Mon, 14 Jul 2025 11:24:59 -0600
Subject: [PATCH] doc: contribute: Add multiline property style guide

Add guidelines for how to split long property values across multiple
lines. This documents the style that is enforced by the devicetree
linter.

Link: https://github.com/zephyrproject-rtos/zephyr/pull/92334

Signed-off-by: Keith Short <keithshort@google.com>
---
 doc/contribute/style/devicetree.rst    | 10 +++++
 doc/contribute/style/style-example.dts | 53 ++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 doc/contribute/style/style-example.dts

diff --git a/doc/contribute/style/devicetree.rst b/doc/contribute/style/devicetree.rst
index 9578a750f7a02..90d8bba00449b 100644
--- a/doc/contribute/style/devicetree.rst
+++ b/doc/contribute/style/devicetree.rst
@@ -17,3 +17,13 @@ Devicetree Style Guidelines
     definitions.
   * Don't insert empty lines before a dedenting ``};``.
   * Insert a single empty line to separate nodes at the same hierarchy level.
+  * When splitting long property values across multiple lines, specify the first
+    value on the same line as the opening bracket (``<`` or ``[``). Place the
+    closing bracket and semicolon (``>;`` or ``];``) on the same line after
+    the final value of the property.
+
+Examples:
+
+.. literalinclude:: style-example.dts
+  :language: devicetree
+  :start-after: start-after-here
diff --git a/doc/contribute/style/style-example.dts b/doc/contribute/style/style-example.dts
new file mode 100644
index 0000000000000..9648b8e61ee2b
--- /dev/null
+++ b/doc/contribute/style/style-example.dts
@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Demonstration of permitted and disallowed coding style for devicetree files.
+ */
+
+/* start-after-here */
+
+/dts-v1/;
+
+/ {
+	/* Node labels use the "_" separator, but node names use "-". */
+	psa_rng: psa-rng {
+		compatible = "zephyr,psa-crypto-rng";
+		status = "okay";
+	};
+
+	ramdisk0 {
+		compatible = "zephyr,ram-disk";
+		/* Property names use the "-" separator. */
+		disk-name = "RAM";
+		sector-size = <512>;
+		sector-count = <128>;
+	};
+
+	periph0 {
+		/* Wrap array values to conform with line lengths. Indent
+		 * continuation so that values align.
+		 */
+		pinctrl-0 = <&periph0_siga_px0_default &periph0_sigb_py7_default
+			     &periph0_sigc_pz1_default>;
+		pinctrl-names = "default";
+	};
+
+	mipi-dbi {
+		compatible = "zephyr,mipi-dbi-spi";
+
+		lcd0: lcd@0 {
+			compatible = "sitronix,st7735r";
+			/* Split array values across multiple lines to help readability. */
+			gamctrp1 = [10 0E 02 03
+				    0E 07 02 07
+				    0A 12 27 37
+				    00 0D 0E 10];
+			gamctrn1 = [10 0E 03 03
+				    0F 06 02 08
+				    0A 13 26 36
+				    00 0D 0E 10];
+		};
+	};
+};