The nau8825 driver defines several DAPM widget names that are used for
audio routing in the Device Tree. However, these strings are not
documented in the binding file.

This forces developers to read the C source to discover the valid
names, which can be inefficient and error-prone.

Add a list of the input and output widget names to the binding's
description to make it self-contained and improve the user
experience for board bring-up.

Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
---
 .../devicetree/bindings/sound/nuvoton,nau8825.yaml   | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
index a54f194a0..cb1c82aa3 100644
--- a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
+++ b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
@@ -9,6 +9,18 @@ title: NAU8825 audio CODEC
 maintainers:
   - John Hsu <KCHSU0@nuvoton.com>
 
+description: |
+  NAU8825 audio CODEC
+
+  Valid routing names defined in the driver for this codec include:
+
+    Outputs:
+      * HPOL : Left Headphone Output
+      * HPOR : Right Headphone Output
+
+    Inputs:
+      * MIC : Microphone Input
+
 allOf:
   - $ref: dai-common.yaml#
 
-- 
2.39.5

On 09/08/2025 17:18, Jihed Chaibi wrote:
> The nau8825 driver defines several DAPM widget names that are used for
> audio routing in the Device Tree. However, these strings are not
> documented in the binding file.
> 
> This forces developers to read the C source to discover the valid
> names, which can be inefficient and error-prone.

Reading snd_soc_dapm_route can be automatize/scripted, so I don't
consider it error prone or difficult, comparing to reading free form
text in any documentation.

> 
> Add a list of the input and output widget names to the binding's
> description to make it self-contained and improve the user
> experience for board bring-up.
> 
> Signed-off-by: Jihed Chaibi <jihed.chaibi.dev@gmail.com>
> ---
>  .../devicetree/bindings/sound/nuvoton,nau8825.yaml   | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> index a54f194a0..cb1c82aa3 100644
> --- a/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> +++ b/Documentation/devicetree/bindings/sound/nuvoton,nau8825.yaml
> @@ -9,6 +9,18 @@ title: NAU8825 audio CODEC
>  maintainers:
>    - John Hsu <KCHSU0@nuvoton.com>
>  
> +description: |
> +  NAU8825 audio CODEC
> +
> +  Valid routing names defined in the driver for this codec include:
Describe pins on the device or device properties instead.

Best regards,
Krzysztof