[Freedreno] [PATCH v5 1/4] dt-bindings: display/msm: convert MDP5 schema to YAML format

[Marijn Suijten]

On 2023-01-12 15:50:15, Rob Herring wrote:
> On Wed, Jan 11, 2023 at 11:35:53PM +0100, Marijn Suijten wrote:
> > On 2023-01-12 00:31:33, Dmitry Baryshkov wrote:
> > > On 12/01/2023 00:29, Marijn Suijten wrote:
> > > > On 2023-01-10 06:40:27, Dmitry Baryshkov wrote:
> > > >> On 09/01/2023 09:49, Marijn Suijten wrote:
> > > >>> On 2023-01-09 07:01:49, Dmitry Baryshkov wrote:
> > > > <snip>
> > > >>>> +    description: |
> > > >>>
> > > >>> Should multiline descriptions be treated as a oneline string with `>`?
> 
> Depends if you want to keep paragraphs. Generally, we use '|' or 
> nothing. If just a colon (or ???), then I think you want '>'.

But doesn't that also affect how lines within paragraphs are flowed?
Arguably it's only GitHub that doesn't "ignore" manual single newlines,
the Markdown (and maybe also RST?) spec AFAIK state that multiline
blocks will be turned into a single paragraph (automatically reflowing
to width).

> I get tired of saying to drop unnecessary '|' in reviews. It would be 
> nice to analyze the text to check what's needed automatically.

And that's just one of the many things...

> > > >> Ack, I'm fine with either of them, let's use the >
> > > >>
> > > >>>
> > > >>>> +      Contains the list of output ports from DPU device. These ports
> > > >>>> +      connect to interfaces that are external to the DPU hardware,
> > > >>>> +      such as DSI, DP etc. MDP5 devices support up to 4 ports::
> > > >>>
> > > >>> How do these double colons render?  Is this intentional?
> > > >>
> > > >> double colons is an escape for a single colon if I remember correcly.
> > > > 
> > > > I thought no escaping was necessary here, especially since this is
> > > > already a value - it is a multiline string.
> > > 
> > > I was mostly following examples, grep :: through the dt-bindings.
> > 
> > Saw that, maybe these "freeform" description strings are intended to be
> > RST to support more elaborate rendering if/when that happens?
> 
> No, though some experiments have been done in that regard. It seemed to 
> work.

Hmm, the question is what format description blocks should adhere to,
and if a double colon here makes sense and/or is required?

> > > >> BTW: how to render the DT schema?
> > > > 
> > > > I'm not sure if there's currently any rendering tool to view these docs
> > > > in a "friendly" manner, e.g. an html page, or whether they're only used
> > > > as specifications for DT validation.
> > > 
> > > Probably there will be one at some point. It might make good addition to 
> > > devicetree.org.
> > 
> > Would be super cool to have some "interactive" / properly
> > rendered/colored docs up there for DT :)
> 
> One of the original goals was to transform the DT spec to schema docs 
> and then generate the spec from the schemas.
> 
> There's tools that do json-schema to docs already. They may just work. I 
> haven't looked at them though as that's not really my itch and I simply 
> don't have time. Maybe if we stop reviewing schemas for a while.

Sure, as above we shoudn't have to render anything now nor any time
soon, but it would be helpful to know what kind of format to adhere to
in description blocks.

- Marijn