scripts: dts: Format multi-line comments nicely

[ulfalizer]

Multi-line comments were stuck as-is between /* and */ in the generated
header, which looks ugly and confusing e.g. for multi-line
binding/property descriptions.

Use this format for multi-line comments in the header instead:

/*
 * First line
 * Second line
 *
 * Line after blank line
 */

Also clean up the output a bit by turning some things that were separate
comments into a single multi-line comment. Add some air and reduce line
lengths too.

Before:

/*  Generated by gen_defines.py  */
/*  DTS input file: hifive1.dts.pre.tmp  */
/*  Directories with bindings: $ZEPHYR_BASE/dts/bindings  */

/*  Devicetree node: /cpus/cpu@0/interrupt-controller  */
/*  Binding (compatible = riscv,cpu-intc): $ZEPHYR_BASE/... */
/*  Binding description: This binding describes the RISC-V ...

Some extra lines
for testing  */
#define DT_INST_0_RISCV_CPU_INTC                    1

After:

/*
 * Generated by gen_defines.py
 *
 * DTS input file:
 *   hifive1.dts.pre.tmp
 *
 * Directories with bindings:
 *   $ZEPHYR_BASE/dts/bindings
 */

/*
 * Devicetree node:
 *   /cpus/cpu@0/interrupt-controller
 *
 * Binding (compatible = riscv,cpu-intc):
 *   $ZEPHYR_BASE/dts/bindings/interrupt-controller/...
 *
 * Description:
 *   This binding describes the RISC-V CPU Interrupt Controller
 *
 *   Some extra lines
 *   for testing
 */
#define DT_INST_0_RISCV_CPU_INTC                    1

Also tweak Node.description and Property.description in edtlib to be
strip()ed instead of rstrip()ed. There's probably no reason to
preserving leading whitespace in them either.

[ulfalizer]

This is why I keep nagging about the "...provides a base representation of..." boilerplate btw:

 *
 * Description:
 *   This binding describes the RISC-V CPU Interrupt Controller
 *

It would be nicer if it just said "RISC-V CPU Interrupt Controller" there (described the device without mentioning the binding).

[pabigot]

For:

  dpd-wakeup-sequence:
    type: array
    required: false
    description: >
      Specifies wakeup durations for devices without RDPD.

      Some devices (Macronix MX25R in particular) wake from deep power
      down by a timed sequence of CSn assertion rather than the RDPD
      command.  This property specifies three durations measured in
      nanoseconds: tDPDD (Delay Time for Release from Deep Power-Down
      Mode), tCDRP (CSn Toggling Time before Release from Deep
      Power-Down Mode), antRDP (Recovery Time for Release from Deep
      Power-Down Mode).

      Absence of this property indicates that the RDPD command should be
      used to wake the chip from Deep Power-Down mode.

I would previously get:

/*  Specifies wakeup durations for devices without RDPD.
Some devices (Macronix MX25R in particular) wake from deep power down by a timed sequence of CSn assertion rather than the RDPD command.  This property specifies three durations measured in nanoseconds: tDPDD (Delay Time for Release from Deep Power-Down Mode), tCDRP (CSn Toggling Time before Release from Deep Power-D
own Mode), antRDP (Recovery Time for Release from Deep Power-Down Mode).
Absence of this property indicates that the RDPD command should be used to wake the chip from Deep Power-Down mode.  */

I now get:

/*
 * Specifies wakeup durations for devices without RDPD.
 * Some devices (Macronix MX25R in particular) wake from deep power down by a timed sequence of CSn assertion rather than the RDPD command.  This property specifies three durations measured in nanoseconds: tDPDD (Delay Time for Release from Deep Power-Down Mode), tCDRP (CSn Toggling Time before Release from Deep Power-Down Mode), antRDP (Recovery Time for Release from Deep Power-Down Mode).
 * Absence of this property indicates that the RDPD command should be used to wake the chip from Deep Power-Down mode.
 */

If we're going for readability I'd rather see this, with some reasonable wrap length like 78 characters.

/*
 * Specifies wakeup durations for devices without RDPD.
 *
 * Some devices (Macronix MX25R in particular) wake from deep power
 * down by a timed sequence of CSn assertion rather than the RDPD
 * command.  This property specifies three durations measured in
 * nanoseconds: tDPDD (Delay Time for Release from Deep Power-Down
 * Mode), tCDRP (CSn Toggling Time before Release from Deep Power-Down
 * Mode), antRDP (Recovery Time for Release from Deep Power-Down
 * Mode).
 *
 * Absence of this property indicates that the RDPD command should be
 * used to wake the chip from Deep Power-Down mode.
 */

[ulfalizer]

@pabigot
What does the .yaml file look like? That second one is what I intended.

Oh... nm, you pasted it there. Does changing > to | change anything?

I'll experiment a bit.

[ulfalizer]

Ah, yeah, it's because > removes newlines. | fixes it.

See the documentation updates in this PR as well. I'll go through all the bindings and change > to |.

This is why consistency is overrated. Better to slightly improve everything after you copy it. Then other people will copy the improved version around in turn. ;)

[pabigot]

@pabigot
What does the .yaml file look like?

I provided it at the top of my comment.

That second one is what I intended.

OK, but I think it's unreadable having one line of unbounded length per paragraph. I want to see the third option where paragraphs are separated and wrap at a reasonable length.

However, it appears I can get that by using the literal style, as you just noted too.

I'd intended to propose that you format each line as a paragraph, but that would break the literal style. So I think this is fine as is---and I'm not really in favor of you doing a global change of > with | in everybody's binding file. I'll use it in the cases where I think it's important.