Organize the descriptions in the bindings

[rruuaanng]

Is your enhancement proposal related to a problem? Please describe.

There are still many descriptions like the one below in the current dts/bindings, which are actually too redundant. e.g.:

• This is a representation of
• .... node
• This binding gives a representation of

I think the best description would be this:

• nRF7002 Wi-Fi chip with QSPI interface
• STM32 USB HS PHY controller
• ITE it8xxx2 PECI

In other words, describe the hardware itself without excessive explanation.

Describe the solution you'd like

Let's clean them up! There are too many of them. Let's tidy up the list items while cleaning them up
— I'm just trying to take the easy way out.

• cpu dts: cpu: Make descriptions consistent #86215
• wifi dts: wifi: Simplify the description of the binding #86266
• cache dts: cache: Simplify the description of the binding #86268
• gpio dts: gpio: Simplify the description of the binding #86389
• mbox dts: mbox: Simplify the description of the binding #86391
• i2c dts: i2c: Simplify the description of the binding #86390
• misc dts: misc: Simplify the description of the binding #86392
• net/wireless dts: net: wireless: Simplify the description of the binding #86393
• dai dts: dai: Simplify the description of the binding #86750
• pinctrl dts: pinctrl: Simplify the description of the binding #86752
• dma dts: dma: Simplify the description of the binding #87955
• spi
• tach
• timer
• watchdog
• usb
• rtc
• sd
• riscv
• shi
• sdhc
• rng
• smbus
• sram
• Look up dts: Simplify the description of the binding  #87958

Describe alternatives you've considered

Additional context

[henrikbrixandersen]

I would argue that we should also introduce a "title" tag for the short title of the binding while doing this, similar as to what is used in DTSchema, and reserve the "description" for a longer text, complete with binding examples and so on. Thoughts? @mbolivar

[rruuaanng]

I noticed that some bindings distinguish between the title and description using this format, such as in nxp,mbox-mailbox.yaml:

description: |
  NXP Mailbox Unit as Zephyr MBOX.

  This NXP Mailbox driver implements Multi-Channel Inter-Processor Mailbox (MBOX) API
  around NXP Inter-CPU Mailbox peripheral IP block.

  The NXP Inter-CPU Mailbox provides up to thirty-two user defined interrupts.
  This driver uses 4 interrupts for mbox signalling mode per each channel,
  4 interrupts for mxbox data transfer mode per each channel and 24 as 3 bytes
  for data.

(Maybe it would be enough to just add some practical guidelines for bindings?)

[decsny]

I personally think all of these can be done in one PR, and maybe even one commit, if its the same few words being deleted in every file, all the PRs are generating a lot of review noise

[rruuaanng]

This might cause difficulties similar to those encountered with the treewide changes, where some maintainers had suggestions, but when grouped into a single PR, it exceeded the maximum number of people that GitHub can ping, which meant I missed out on some valuable feedback.
(So, I believe this approach would be better, even though it may result in some email noise.)

But I see your point, and I agree with it. I'll group some of the smaller files into a single PR, while for larger driver modules, I'll still open separate PRs to handle them individually, to avoid the potential issues I mentioned above.

[kartben]

I would argue that we should also introduce a "title" tag for the short title of the binding while doing this, similar as to what is used in DTSchema, and reserve the "description" for a longer text, complete with binding examples and so on. Thoughts? @mbolivar

+1
But like @rruuaanng suggested I think a reasonable first step, which can only make the move to using a title property easier, is to generalize the use of the following format:

Short sentence (aka title).

More text.
After.
A blank line.

[rruuaanng]

I would argue that we should also introduce a "title" tag for the short title of the binding while doing this, similar as to what is used in DTSchema, and reserve the "description" for a longer text, complete with binding examples and so on. Thoughts? @mbolivar

+1 But like @rruuaanng suggested I think a reasonable first step, which can only make the move to using a title property easier, is to generalize the use of the following format:

Short sentence (aka title).

More text.
After.
A blank line.

Oh, alright. It looks like everyone likes this. I'll get it done in my spare time, at least after most of my PRs are taken care of.
(I don't think this is particularly urgent.)

[rruuaanng]

@kartben @henrikbrixandersen
It seems that the title keyword was deprecated in the past for some reason. Do we still need to restore it? If the answer is yes, I think we should make title an optional keyword.

        # Descriptive errors for legacy bindings.
        legacy_errors = {
            "#cells": "expected *-cells syntax",
            "child": "use 'bus: <bus>' instead",
            "child-bus": "use 'bus: <bus>' instead",
            "parent": "use 'on-bus: <bus>' instead",
            "parent-bus": "use 'on-bus: <bus>' instead",
            "sub-node": "use 'child-binding' instead",
            "title": "use 'description' instead",
        }

[mbolivar]

@rruuaanng ah, I see now that #86533 is related to this issue -- this would have been helpful for me to know when reviewing that PR.

I think the discussion in this issue should be enough for you to make the documentation updates I requested in the PR -- think you can make that work?

Probably also worth adding a fixes: #86265 to #86533 's issue description in case other people are confused as I was.