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

[Nicolas Ferre <nicolas.ferre-AIFe0yeh4nAAvxtiuMwx3w@public.gmane.org>]

Le 01/09/2015 19:35, Tim Bird a écrit :
> On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring <robherring2-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org> wrote:
> ...
>>> +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