backlight: backlight: Improve backlight_ops documentation

Improve the documentation for backlight_ops 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 56e51ebab74020f088a2143f99b64066b676a4c2..4ff60774ae22450a0d034f0faa71bc277c56d40e 100644 (file)
--- a/include/linux/backlight.h
+++ b/include/linux/backlight.h
@@ -55,19 +55,66 @@ enum backlight_scale {
 struct backlight_device;
 struct fb_info;
 
+/**
+ * struct backlight_ops - backlight operations
+ *
+ * The backlight operations are specified when the backlight device is registered.
+ */
 struct backlight_ops {
+       /**
+        * @options: Configure how operations are called from the core.
+        *
+        * The options parameter is used to adjust the behaviour of the core.
+        * Set BL_CORE_SUSPENDRESUME to get the update_status() operation called
+        * upon suspend and resume.
+        */
        unsigned int options;
 
 #define BL_CORE_SUSPENDRESUME  (1 << 0)
 
-       /* Notify the backlight driver some property has changed */
+       /**
+        * @update_status: Operation called when properties have changed.
+        *
+        * Notify the backlight driver some property has changed.
+        * The update_status operation is protected by the update_lock.
+        *
+        * The backlight driver is expected to use backlight_is_blank()
+        * to check if the display is blanked and set brightness accordingly.
+        * update_status() is called when any of the properties has changed.
+        *
+        * RETURNS:
+        *
+        * 0 on success, negative error code if any failure occurred.
+        */
        int (*update_status)(struct backlight_device *);
-       /* Return the current backlight brightness (accounting for power,
-          fb_blank etc.) */
+
+       /**
+        * @get_brightness: Return the current backlight brightness.
+        *
+        * The driver may implement this as a readback from the HW.
+        * This operation is optional and if not present then the current
+        * brightness property value is used.
+        *
+        * RETURNS:
+        *
+        * A brightness value which is 0 or a positive number.
+        * On failure a negative error code is returned.
+        */
        int (*get_brightness)(struct backlight_device *);
-       /* Check if given framebuffer device is the one bound to this backlight;
-          return 0 if not, !=0 if it is. If NULL, backlight always matches the fb. */
-       int (*check_fb)(struct backlight_device *, struct fb_info *);
+
+       /**
+        * @check_fb: Check the framebuffer device.
+        *
+        * Check if given framebuffer device is the one bound to this backlight.
+        * This operation is optional and if not implemented it is assumed that the
+        * fbdev is always the one bound to the backlight.
+        *
+        * RETURNS:
+        *
+        * If info is NULL or the info matches the fbdev bound to the backlight return true.
+        * If info does not match the fbdev bound to the backlight return false.
+        */
+       int (*check_fb)(struct backlight_device *bd, struct fb_info *info);
 };
 
 /* This structure defines all the properties of a backlight */