[settings] Improve key name documentation. MER#1554

Remove references to gconf and try to improve explanations.

No functional changes.

event-input.h

@@ -40,20 +40,38 @@
  * Settings
  * ========================================================================= */
 
-/** Path to the GConf settings for the event input */
+/** Prefix for event input setting keys */
 # define MCE_SETTING_EVENT_INPUT_PATH       "/system/osso/dsm/event_input"
 
 # ifdef ENABLE_DOUBLETAP_EMULATION
-/** Path to the use Fake Double Tap setting */
+/** Whether double tap emulation is enabled
+ *
+ * When enabled, mce does double tap detection from "normal" touch events
+ * that are received in display off an lpm states.
+ */
 #  define MCE_SETTING_USE_FAKE_DOUBLETAP    MCE_SETTING_EVENT_INPUT_PATH "/use_fake_double_tap"
 #  define MCE_DEFAULT_USE_FAKE_DOUBLETAP    true
 # endif
 
-/** Path to the touch unblock delay setting */
+/** How long to delay touch unblock after display power up [ms]
+ *
+ * This can be used to fine tune input policy to make it less
+ * likely that accidental touch events reach ui during in-call
+ * proximity blanking etc.
+ */
 # define MCE_SETTING_TOUCH_UNBLOCK_DELAY    MCE_SETTING_EVENT_INPUT_PATH "/touch_unblock_delay"
 # define MCE_DEFAULT_TOUCH_UNBLOCK_DELAY    100
 
-/** Input device grabbing allowed setting */
+/** What kind of evdev sources mce is allowed to grab [bitmask]
+ *
+ * By default mce grabs evdev sources dealing with touch events and volume
+ * keys under certain circumstances.
+ *
+ * If this is not desirable for some reason (for example touchscreens
+ * that use multitouch protocol B for reporting should not be grabbed),
+ * the default value of this setting should be overridden in hw adaptation
+ * specific configuration.
+ */
 # define MCE_SETTING_INPUT_GRAB_ALLOWED     MCE_SETTING_EVENT_INPUT_PATH "/input_grab_allowed"
 # define MCE_INPUT_GRAB_ALLOW_NONE          (0)
 # define MCE_INPUT_GRAB_ALLOW_TS            (1<<0)

modules/doubletap.h

@@ -52,10 +52,10 @@ typedef enum
         DBLTAP_ENABLE_NO_PROXIMITY = 2,
 } dbltap_mode_t;
 
-/** Path to the GConf settings for the doubletap module */
+/** Prefix for doubletap setting keys */
 # define MCE_SETTING_DOUBLETAP_PATH      "/system/osso/dsm/doubletap"
 
-/** Path to the doubletap  mode GConf setting */
+/** When doubletap detection is enabled */
 # define MCE_SETTING_DOUBLETAP_MODE      MCE_SETTING_DOUBLETAP_PATH "/mode"
 # define MCE_DEFAULT_DOUBLETAP_MODE      2 // = DBLTAP_ENABLE_NO_PROXIMITY
 

modules/led.h

@@ -82,14 +82,14 @@
  * Settings
  * ========================================================================= */
 
-/** Path to the GConf settings for the display */
+/** Prefix for led setting keys */
 #define MCE_SETTING_LED_PATH			"/system/osso/dsm/leds"
 
-/** Setting for: sw led breathing enabled/disabled */
+/** Whether sw based led breathing is enabled */
 #define MCE_SETTING_LED_SW_BREATH_ENABLED	MCE_SETTING_LED_PATH"/sw_breath_enabled"
 #define MCE_DEFAULT_LED_SW_BREATH_ENABLED	true
 
-/** Setting for: minimum battery level for breathing */
+/** Mimimum battery level to allow led breathing without charger */
 #define MCE_SETTING_LED_SW_BREATH_BATTERY_LIMIT	MCE_SETTING_LED_PATH"/sw_breath_battery_limit"
 #define MCE_DEFAULT_LED_SW_BREATH_BATTERY_LIMIT	101
 

modules/memnotify.h

@@ -5,24 +5,28 @@
  * Settings
  * ========================================================================= */
 
-/** Base path for memnotify configuration */
+/** Prefix for memnotify setting keys */
 # define MCE_SETTING_MEMNOTIFY_PATH             "/system/osso/dsm/memnotify"
 
 /** Memnotify warning level configuration */
 # define MCE_SETTING_MEMNOTIFY_WARNING_PATH     MCE_SETTING_MEMNOTIFY_PATH"/warning"
 
+/** Warning threshold for used memory [pages] */
 # define MCE_SETTING_MEMNOTIFY_WARNING_USED     MCE_SETTING_MEMNOTIFY_PATH"/warning/used"
 # define MCE_DEFAULT_MEMNOTIFY_WARNING_USED     0 // = disabled
 
+/** Warning threshold for active memory [pages] */
 # define MCE_SETTING_MEMNOTIFY_WARNING_ACTIVE   MCE_SETTING_MEMNOTIFY_PATH"/warning/active"
 # define MCE_DEFAULT_MEMNOTIFY_WARNING_ACTIVE   0 // = disabled
 
 /** Memnotify critical level configuration */
 # define MCE_SETTING_MEMNOTIFY_CRITICAL_PATH    MCE_SETTING_MEMNOTIFY_PATH"/critical"
 
+/** Critical threshold for used memory [pages] */
 # define MCE_SETTING_MEMNOTIFY_CRITICAL_USED    MCE_SETTING_MEMNOTIFY_PATH"/critical/used"
 # define MCE_DEFAULT_MEMNOTIFY_CRITICAL_USED    0 // = disabled
 
+/** Critical threshold for active memory [pages] */
 # define MCE_SETTING_MEMNOTIFY_CRITICAL_ACTIVE  MCE_SETTING_MEMNOTIFY_PATH"/critical/active"
 # define MCE_DEFAULT_MEMNOTIFY_CRITICAL_ACTIVE  0 // = disabled
 

modules/powersavemode.h

@@ -25,22 +25,31 @@
  * Settings
  * ========================================================================= */
 
-/** Path to the GConf settings for energy management */
+/** Prefix for energy management setting keys */
 # define MCE_SETTING_EM_PATH                    "/system/osso/dsm/energymanagement"
 
-/** Path to the power saving mode GConf setting */
+/** Whether power save mode activation is allowed
+ *
+ * Power Save Mode = when battery percentage falls below some threshold,
+ * potentially power hungry features are disabled.
+ *
+ * Note: This is legacy feature for Nokia devices. While the triggering
+ *       mechanism and ui side notifications are fully working, the
+ *       usefulness of it is rather limited since cellular, networking
+ *       etc middleware does not (yet) react to psm state changes.
+ */
 # define MCE_SETTING_EM_ENABLE_PSM               MCE_SETTING_EM_PATH "/enable_power_saving"
 # define MCE_DEFAULT_EM_ENABLE_PSM               false
 
-/** Path to the forced power saving mode GConf setting */
+/** Whether power save mode should be active always when not charging */
 # define MCE_SETTING_EM_FORCED_PSM               MCE_SETTING_EM_PATH "/force_power_saving"
 # define MCE_DEFAULT_EM_FORCED_PSM               false
 
-/** Path to the power save mode threshold GConf setting */
+/** Threshold when to activate PSM [battery %] */
 # define MCE_SETTING_EM_PSM_THRESHOLD            MCE_SETTING_EM_PATH "/psm_threshold"
 # define MCE_DEFAULT_EM_PSM_THRESHOLD            20
 
-/** Setting for: Possible PSM thresholds
+/** List of 5 possible PSM threshold [battery %]
  *
  * Hint for settings UI. Not used by MCE itself.
  */

modules/proximity.h

@@ -22,14 +22,14 @@
 #ifndef PROXIMITY_H_
 # define PROXIMITY_H_
 
-/** Path to the GConf settings for the proximity */
+/** Prefix for proximity sensor setting keys */
 # define MCE_SETTING_PROXIMITY_PATH             "/system/osso/dsm/proximity"
 
-/** Proximity sensor enabled GConf setting */
+/** Whether MCE is allowed to use proximity sensor */
 # define MCE_SETTING_PROXIMITY_PS_ENABLED       MCE_SETTING_PROXIMITY_PATH "/ps_enabled"
 # define MCE_DEFAULT_PROXIMITY_PS_ENABLED       true
 
-/** Proximity sensor acts as lid sensor setting */
+/** Whether proximity sensor should be treated as cover closed sensor */
 # define MCE_SETTING_PROXIMITY_PS_ACTS_AS_LID   MCE_SETTING_PROXIMITY_PATH "/ps_acts_as_lid"
 # define MCE_DEFAULT_PROXIMITY_PS_ACTS_AS_LID   false
 

powerkey.h

@@ -27,7 +27,7 @@
  * Settings
  * ========================================================================= */
 
-/** Path to the GConf settings for the powerkey module */
+/** Prefix for powerkey setting keys */
 # define MCE_SETTING_POWERKEY_PATH                 "/system/osso/dsm/powerkey"
 
 /** Power key action enable modes */
@@ -46,7 +46,7 @@ typedef enum
     PWRKEY_ENABLE_NO_PROXIMITY2 = 3,
 } pwrkey_enable_mode_t;
 
-/** Powerkey mode setting */
+/** When mce should react to power key presses */
 # define MCE_SETTING_POWERKEY_MODE                 MCE_SETTING_POWERKEY_PATH "/mode"
 # define MCE_DEFAULT_POWERKEY_MODE                 1 // = PWRKEY_ENABLE_ALWAYS
 
@@ -59,56 +59,61 @@ typedef enum
     PWRKEY_BLANK_TO_LPM         = 1,
 } pwrkey_blanking_mode_t;
 
-/** Powerkey blanking mode setting */
+/** How power key "blank" action should behave */
 # define MCE_SETTING_POWERKEY_BLANKING_MODE        MCE_SETTING_POWERKEY_PATH "/blanking_mode"
 # define MCE_DEFAULT_POWERKEY_BLANKING_MODE        0 // = PWRKEY_BLANK_TO_OFF
 
-/** Powerkey press count for proximity sensor override */
+/** How many consequent power key presses trigger proximity override
+ *
+ * Rapidly pressing powerkey multiple times can be used to override
+ * proximity sensor covered state. Can be useful in situations where
+ * faulty / dirty / otherwise misbehaving proximity sensor does not
+ * allow turning display on.
+ */
 # define MCE_SETTING_POWERKEY_PS_OVERRIDE_COUNT    MCE_SETTING_POWERKEY_PATH "/ps_override_count"
 # define MCE_DEFAULT_POWERKEY_PS_OVERRIDE_COUNT    3
 
-/** Maximum delay between powerkey presses for ps override */
+/** Maximum delay between powerkey presses for ps override [ms]*/
 # define MCE_SETTING_POWERKEY_PS_OVERRIDE_TIMEOUT  MCE_SETTING_POWERKEY_PATH "/ps_override_timeout"
 # define MCE_DEFAULT_POWERKEY_PS_OVERRIDE_TIMEOUT  333
 
-/** Long press timeout setting */
+/** Threshold for long power key press [ms] */
 # define MCE_SETTING_POWERKEY_LONG_PRESS_DELAY     MCE_SETTING_POWERKEY_PATH "/long_press_delay"
 # define MCE_DEFAULT_POWERKEY_LONG_PRESS_DELAY     1500
 
-/** Double press timeout setting */
+/** Maximum wait time in between double power key presses [ms] */
 # define MCE_SETTING_POWERKEY_DOUBLE_PRESS_DELAY   MCE_SETTING_POWERKEY_PATH "/double_press_delay"
 # define MCE_DEFAULT_POWERKEY_DOUBLE_PRESS_DELAY   400
 
-/** Setting for single press actions from display on */
+/** Actions to take on single power key press from display on */
 # define MCE_SETTING_POWERKEY_ACTIONS_SINGLE_ON    MCE_SETTING_POWERKEY_PATH "/actions_single_on"
 # define MCE_DEFAULT_POWERKEY_ACTIONS_SINGLE_ON    "blank,tklock"
 
-/** Setting for double press actions from display on */
+/** Actions to take on double power key press from display on */
 # define MCE_SETTING_POWERKEY_ACTIONS_DOUBLE_ON    MCE_SETTING_POWERKEY_PATH "/actions_double_on"
 # define MCE_DEFAULT_POWERKEY_ACTIONS_DOUBLE_ON    "blank,tklock,devlock,vibrate"
 
-/** Setting for long press actions from display on */
+/** Actions to take on long power key press from display on */
 # define MCE_SETTING_POWERKEY_ACTIONS_LONG_ON      MCE_SETTING_POWERKEY_PATH "/actions_long_on"
 # define MCE_DEFAULT_POWERKEY_ACTIONS_LONG_ON      "shutdown"
 
-/** Setting for single press actions from display off */
+/** Actions to take on single power key press from display off */
 # define MCE_SETTING_POWERKEY_ACTIONS_SINGLE_OFF   MCE_SETTING_POWERKEY_PATH "/actions_single_off"
 # define MCE_DEFAULT_POWERKEY_ACTIONS_SINGLE_OFF   "unblank"
 
-/** Setting for double press actions from display off */
+/** Actions to take on double power key press from display off */
 # define MCE_SETTING_POWERKEY_ACTIONS_DOUBLE_OFF   MCE_SETTING_POWERKEY_PATH "/actions_double_off"
-/** Default actions for double press while display is off */
 # define MCE_DEFAULT_POWERKEY_ACTIONS_DOUBLE_OFF   "unblank,tkunlock"
 
-/** Setting for long press actions from display off
+/** Actions to take on long power key press from display off
  *
  * Note: If kernel side reports immediately power key press + release
  *       when device is suspended, detecting long presses might not
  *       work when display is off -> leave unset by default. */
 # define MCE_SETTING_POWERKEY_ACTIONS_LONG_OFF     MCE_SETTING_POWERKEY_PATH "/actions_long_off"
 # define MCE_DEFAULT_POWERKEY_ACTIONS_LONG_OFF     ""
 
-/** Setting keys for touch screen gesture actions */
+/** Actions to take on touchscreen gesture N */
 # define MCE_SETTING_POWERKEY_ACTIONS_GESTURE0     MCE_SETTING_POWERKEY_PATH "/actions_gesture0"
 # define MCE_DEFAULT_POWERKEY_ACTIONS_GESTURE0     "unblank"
 
@@ -145,7 +150,7 @@ typedef enum
 /** Number of configurable touchscreen gestures */
 # define POWERKEY_ACTIONS_GESTURE_COUNT            11
 
-/** Setting keys for configurable dbus actions */
+/** What to send when dbus action N is taken*/
 # define MCE_SETTING_POWERKEY_DBUS_ACTION1         MCE_SETTING_POWERKEY_PATH "/dbus_action1"
 # define MCE_DEFAULT_POWERKEY_DBUS_ACTION1         "event1"