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>
---
 .../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..0f665b13c126 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 in every device binding. 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 normal 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 Tue, Jul 21, 2026 at 12:30:32PM +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>
> ---
>  .../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..0f665b13c126 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 in every device binding. A list of one or more

I think this first sentence doesn't really get across the "final device"
point you were going for. I think it should probably say something like
"although expected outside of bindings describing common properties or
sub-blocks of more complex devices." I think being clear only benefits
us here.

> +  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 normal 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 21/07/2026 17:44, Conor Dooley wrote:
>>
>> diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst
>> index 3ffd0828617a..0f665b13c126 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 in every device binding. A list of one or more
> 
> I think this first sentence doesn't really get across the "final device"
> point you were going for. I think it should probably say something like
> "although expected outside of bindings describing common properties or
> sub-blocks of more complex devices." I think being clear only benefits
> us here.

Ack

Best regards,
Krzysztof