Document already used rules about example DTS in the binding:

 - All final device bindings (except sub-block of more complex devices)
   should have an example.

 - Phandles do not need to be resolvable - Sashiko already provided
   incorrect review, so this might help it to understand the concept.

 - Example should be complete, readable (use known defines), without
   'status' property.

Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>

---

Changes in v2:
1. Rewrite "optional" exception, as Conor suggested.
2. "normal" -> "typical" in last sentence about status.
---
 .../devicetree/bindings/writing-schema.rst          | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
index 3ffd0828617a..d31b94300f46 100644
--- a/Documentation/devicetree/bindings/writing-schema.rst
+++ b/Documentation/devicetree/bindings/writing-schema.rst
@@ -127,9 +127,16 @@ additionalProperties / unevaluatedProperties
         two above cases ('false').
 
 examples
-  Optional. A list of one or more DTS hunks implementing this binding only.
-  Example should not contain unrelated device nodes, e.g. consumer nodes in a
-  provider binding, other nodes referenced by phandle.
+  Optional, although expected outside of bindings describing common properties
+  or sub-blocks of more complex devices. A list of one or more DTS hunks
+  implementing this binding only.  Example should not contain unrelated device
+  nodes, e.g. consumer nodes in a provider binding, other nodes referenced by
+  phandles or node labels which are not directly referenced in the example
+  itself. Phandles in the example do not have to be resolvable.  The example
+  must be complete as much as possible - have most of the properties - and look
+  readable to developers, thus for example use known defines for interrupt or
+  GPIO flags. Example should not contain 'status' property in typical cases.
+
   Note: YAML doesn't allow leading tabs, so spaces must be used instead.
 
 Unless noted otherwise, all above schema properties are required.
-- 
2.53.0

On Wed, 22 Jul 2026 08:22:41 +0200, Krzysztof Kozlowski wrote:
> Document already used rules about example DTS in the binding:
> 
>  - All final device bindings (except sub-block of more complex devices)
>    should have an example.
> 
>  - Phandles do not need to be resolvable - Sashiko already provided
>    incorrect review, so this might help it to understand the concept.
> 
>  - Example should be complete, readable (use known defines), without
>    'status' property.
> 
> Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@oss.qualcomm.com>
> 
> ---
> 
> Changes in v2:
> 1. Rewrite "optional" exception, as Conor suggested.
> 2. "normal" -> "typical" in last sentence about status.
> ---
>  .../devicetree/bindings/writing-schema.rst          | 13 ++++++++++---
>  1 file changed, 10 insertions(+), 3 deletions(-)
> 

Applied, thanks!