[PATCH v2] docs: leds: uleds: Make the documentation match the code.

[Björn Persson]

From: Björn Persson <Bjorn@Rombobjörn.se>

The description in uleds.rst omits the field max_brightness and claims
falsely that the maximum brightness is always 255. Leaving max_brightness
uninitialized or omitting it when writing to /dev/uleds won't work. It
must be given a value, and that value becomes the maximum brightness.

The document is also wrong about the type of brightness values. It says
that a single byte shall be read at a time. That's actually not allowed.
Then the word "unsigned" gives the impression that the type is unsigned.
In fact a signed type is used even though the values are never negative.

Change the document to describe the true API.

Signed-off-by: Björn Persson <Bjorn@Rombobjörn.se>
---
Changes in v2:
Replaced "given" with "specified" to prevent misinterpretation of "given name", avoided mentioning a type name outside of C code fragments, and rewrote the commit message to read more like speech, as requested.

 Documentation/leds/uleds.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/Documentation/leds/uleds.rst b/Documentation/leds/uleds.rst
index 83221098009c..f985048c641f 100644
--- a/Documentation/leds/uleds.rst
+++ b/Documentation/leds/uleds.rst
@@ -17,16 +17,23 @@ structure to it (found in kernel public header file linux/uleds.h)::
 
     struct uleds_user_dev {
 	char name[LED_MAX_NAME_SIZE];
+	int max_brightness;
     };
 
-A new LED class device will be created with the name given. The name can be
-any valid sysfs device node name, but consider using the LED class naming
-convention of "devicename:color:function".
+A new LED class device will be created with the specified name and maximum
+brightness. The name can be any valid sysfs device node name, but consider
+using the LED class naming convention of "devicename:color:function".
 
-The current brightness is found by reading a single byte from the character
-device. Values are unsigned: 0 to 255. Reading will block until the brightness
-changes. The device node can also be polled to notify when the brightness value
-changes.
+Although max_brightness is signed, only positive values are valid: 1 to INT_MAX.
+
+The current brightness shall be read from the character device like so::
+
+    int brightness;
+    result = read(file, &brightness, sizeof(brightness));
+
+The possible values are 0 to max_brightness. Reading will block until the
+brightness changes. The device node can also be polled to notify when the
+brightness value changes.
 
 The LED class device will be removed when the open file handle to /dev/uleds
 is closed.
-- 
2.54.0