dts: bindings: gpio-leds: improve description

This is the compatible which is used in the blinky sample, so
it's worth trying to add a better example for what you can do with it
in general in the main description.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

dts/bindings/gpio/gpio-leds.yaml

@@ -1,7 +1,36 @@
 # Copyright (c) 2018, Linaro Limited
 # SPDX-License-Identifier: Apache-2.0
 
-description: GPIO LEDs parent node
+description: |
+  This allows you to define a group of LEDs. Each LED in the group is
+  controlled by a GPIO. Each LED is defined in a child node of the
+  gpio-leds node.
+
+  Here is an example which defines three LEDs in the node /leds:
+
+  / {
+  	leds {
+  		compatible = "gpio-leds";
+  		led_0 {
+  			gpios = <&gpio0 1 GPIO_ACTIVE_LOW>;
+  		};
+  		led_1 {
+  			gpios = <&gpio0 2 GPIO_ACTIVE_HIGH>;
+  		};
+  		led_2 {
+  			gpios = <&gpio1 15 (GPIO_PULL_UP | GPIO_ACTIVE_LOW)>;
+  		};
+  	};
+  };
+
+  Above:
+
+  - led_0 is pin 1 on gpio0. The LED is on when the pin is low,
+    and off when the pin is high.
+  - led_1 is pin 2 on gpio0. The LED is on when the pin is high,
+    and off when it is low.
+  - led_2 is pin 15 on gpio1. The LED is on when the pin is low,
+    and the pin's internal pull-up resistor should be enabled.
 
 compatible: "gpio-leds"