On Tue, Sep 01, 2015 at 10:35:44AM -0700, Tim Bird wrote: > On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring <robherring2@xxxxxxxxx> wrote: > > On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@xxxxxxxxxxxx> 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 think part of the suggestion is that we can simply generate the common examples from the tags (as part of formatted doc generation) rather than it being a verbatim paste from a dts file. This has the benefit of not getting that verbatim text of of sync with a dts (because we'll eventually validating the dts files versus the binding doc). Does that still achieve what you want? Keep in mind that we aren't talking about taking away the ability to put an explicit verbatim example, but rather making it an exception case to demonstrate some variants where an author wants to point out different common use cases. -Matt -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html