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

[Matt Porter <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>]

On Wed, Sep 02, 2015 at 10:45:13AM +0200, Nicolas Ferre wrote:
> 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/HQFizaE/u3fw@public.gmane.orgm> 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.

See my comments on Tim's post. In summary, we'd retain the complex type
examples but allow the trivial ones to not bother with it in explicit
source. OTOH, this would have to be a final change in the conversion
process, most likely, because we need all the type: and constraints:
tags present in order to generate a working example.

Of course, that's the same info necessary to validate a dts as well.

Perhaps it's best to look at this as the automated conversion process
that Rob suggested. That is, we'll have the current text (including
all examples) brought into the .yaml file as comments. So we aren't
eliminating examples. Later, if those examples are too trivial to
bother capturing as above, we simply remove and one can dump an example
via a doc generator not unlike my markdown example (which can spit out
pasteable text).

-Matt