Multiline in device-trees bindings

Multiline in device-trees bindings

[David Heidelberg]

Hi.

Often is suggested to drop `|` and `>` for the `description` inside 
device-tree bindings.

I haven't found any recommendation related to the device-tree bindings, 
but from [1] it seems to be even used in example.

My main concern would be, that using block style indicators [2] can make 
text more readable in future, when at some point eye pleasing 
documentation gets generated from the device-tree YAML files.

Would be nice to have consensus when to use them and when not to. Maybe 
add it into documentation or reference YAML documentation with addition 
of specific recommendation for the kernel project?

Thank you

David

[1] 
https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html?highlight=binding#example-schema

[2] https://yaml-multiline.info/

Re: Multiline in device-trees bindings

[Krzysztof Kozlowski]

On 24/04/2022 10:34, David Heidelberg wrote:
> Hi.
> 
> Often is suggested to drop `|` and `>` for the `description` inside 
> device-tree bindings.
> 
> I haven't found any recommendation related to the device-tree bindings, 
> but from [1] it seems to be even used in example.
> 
> My main concern would be, that using block style indicators [2] can make 
> text more readable in future, when at some point eye pleasing 
> documentation gets generated from the device-tree YAML files.

I understand it is about usage of '|' or '>' against nothing marked at
all. In such case I don't see the benefit of using block markers for
cases when they are not needed, because they produce exactly the same
output as one without them. Where is the "more readable"?

It's entirely different of course for text which benefits from block
markers, but no one recommended you to drop block markers in such case,
right?

> 
> Would be nice to have consensus when to use them and when not to. Maybe 
> add it into documentation or reference YAML documentation with addition 
> of specific recommendation for the kernel project?

I think the consensus is already there - when using block markers is
equal to not using them, why adding block markers?

Best regards,
Krzysztof