backlight: backlight: Improve backlight_properties documentation

Improve the documentation for backlight_properties and adapt it to
kernel-doc style.

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Reviewed-by: Daniel Thompson <daniel.thompson@linaro.org>
Reviewed-by: Emil Velikov <emil.l.velikov@gmail.com>
Signed-off-by: Lee Jones <lee.jones@linaro.org>

diff --git a/include/linux/backlight.h b/include/linux/backlight.h
index 4ff6077..3554aef 100644 (file)
--- a/include/linux/backlight.h
+++ b/include/linux/backlight.h
@@ -117,28 +117,102 @@ struct backlight_ops {
        int (*check_fb)(struct backlight_device *bd, struct fb_info *info);
 };
 
-/* This structure defines all the properties of a backlight */
+/**
+ * struct backlight_properties - backlight properties
+ *
+ * This structure defines all the properties of a backlight.
+ */
 struct backlight_properties {
-       /* Current User requested brightness (0 - max_brightness) */
+       /**
+        * @brightness: The current brightness requested by the user.
+        *
+        * The backlight core makes sure the range is (0 to max_brightness)
+        * when the brightness is set via the sysfs attribute:
+        * /sys/class/backlight/<backlight>/brightness.
+        *
+        * This value can be set in the backlight_properties passed
+        * to devm_backlight_device_register() to set a default brightness
+        * value.
+        */
        int brightness;
-       /* Maximal value for brightness (read-only) */
+
+       /**
+        * @max_brightness: The maximum brightness value.
+        *
+        * This value must be set in the backlight_properties passed to
+        * devm_backlight_device_register() and shall not be modified by the
+        * driver after registration.
+        */
        int max_brightness;
-       /* Current FB Power mode (0: full on, 1..3: power saving
-          modes; 4: full off), see FB_BLANK_XXX */
+
+       /**
+        * @power: The current power mode.
+        *
+        * User space can configure the power mode using the sysfs
+        * attribute: /sys/class/backlight/<backlight>/bl_power
+        * When the power property is updated update_status() is called.
+        *
+        * The possible values are: (0: full on, 1 to 3: power saving
+        * modes; 4: full off), see FB_BLANK_XXX.
+        *
+        * When the backlight device is enabled @power is set
+        * to FB_BLANK_UNBLANK. When the backlight device is disabled
+        * @power is set to FB_BLANK_POWERDOWN.
+        */
        int power;
-       /* FB Blanking active? (values as for power) */
-       /* Due to be removed, please use (state & BL_CORE_FBBLANK) */
+
+       /**
+        * @fb_blank: The power state from the FBIOBLANK ioctl.
+        *
+        * When the FBIOBLANK ioctl is called @fb_blank is set to the
+        * blank parameter and the update_status() operation is called.
+        *
+        * When the backlight device is enabled @fb_blank is set
+        * to FB_BLANK_UNBLANK. When the backlight device is disabled
+        * @fb_blank is set to FB_BLANK_POWERDOWN.
+        *
+        * Backlight drivers should avoid using this property. It has been
+        * replaced by state & BL_CORE_FBLANK (although most drivers should
+        * use backlight_is_blank() as the preferred means to get the blank
+        * state).
+        *
+        * fb_blank is deprecated and will be removed.
+        */
        int fb_blank;
-       /* Backlight type */
+
+       /**
+        * @type: The type of backlight supported.
+        *
+        * The backlight type allows userspace to make appropriate
+        * policy decisions based on the backlight type.
+        *
+        * This value must be set in the backlight_properties
+        * passed to devm_backlight_device_register().
+        */
        enum backlight_type type;
-       /* Flags used to signal drivers of state changes */
+
+       /**
+        * @state: The state of the backlight core.
+        *
+        * The state is a bitmask. BL_CORE_FBBLANK is set when the display
+        * is expected to be blank. BL_CORE_SUSPENDED is set when the
+        * driver is suspended.
+        *
+        * backlight drivers are expected to use backlight_is_blank()
+        * in their update_status() operation rather than reading the
+        * state property.
+        *
+        * The state is maintained by the core and drivers may not modify it.
+        */
        unsigned int state;
-       /* Type of the brightness scale (linear, non-linear, ...) */
-       enum backlight_scale scale;
 
 #define BL_CORE_SUSPENDED      (1 << 0)        /* backlight is suspended */
 #define BL_CORE_FBBLANK                (1 << 1)        /* backlight is under an fb blank event */
 
+       /**
+        * @scale: The type of the brightness scale.
+        */
+       enum backlight_scale scale;
 };
 
 struct backlight_device {