Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document

Le 01/09/2015 19:35, Tim Bird a écrit :

On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring [off-list ref] wrote:

quoted

On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter [off-list ref] wrote:

...

quoted

quoted

+example:
+  - dts: |
+      sk11@0 {
+              compatible = "skel,sk11";
+              reg = <0>;
+              spi-max-frequency = <1000000>;
+              spi-cs-high;
+      };

At least in this example, we could generate it. Examples are nice, but
we have dts files full of examples already. I get a fair number of
"fix the example" patches, so maybe we should eliminate the simple
ones.

I would hesitate to eliminate examples.  I've been saved by them on
a few occasions, when the dts files only had one or two instances
of a type of binding, somewhat different from each other, and the example helped
break the tie.  If there's something wrong with the example, it's a sign
of an out-of-date binding doc, just as much as if the text were wrong.
It ought to be possible to validate the example versus the binding doc
(as Pantelis says), so ultimately we should be able to catch errors here
as well.

I back Tim's advice.
Example are so important that I regularly find myself thinking "ah-ha,
okay that's supposed to work like that" after having read the binding
documentation.

Bye,
-- 
Nicolas Ferre