[headers] Improve some mode related comments

Some dbus signals and mode selection specifics can do
with some better code documentation.

Author: Thomas Perl <m@thp.io>
Author: Philippe De Swert <philippe.deswert@jollamobile.com>
Signed-off-by: Philippe De Swert <philippe.deswert@jollamobile.com>

src/usb_moded-dbus.h

@@ -25,13 +25,21 @@
 #define USB_MODE_SERVICE		"com.meego.usb_moded"
 #define USB_MODE_INTERFACE		"com.meego.usb_moded"
 #define USB_MODE_OBJECT			"/com/meego/usb_moded"
+
+/**
+ * sig_usb_state_ind: Notify interested parties of state and mode changes
+ *
+ * This signals both the transient states listed below as well as the "real"
+ * states listed in usb_moded-modes.h.
+ **/
 #define USB_MODE_SIGNAL_NAME		"sig_usb_state_ind"
+
 #define USB_MODE_ERROR_SIGNAL_NAME	"sig_usb_state_error_ind"
 #define USB_MODE_SUPPORTED_MODES_SIGNAL_NAME "sig_usb_supported_modes_ind"
 
 /* supported methods */
-#define USB_MODE_STATE_REQUEST	"mode_request"
-#define USB_MODE_RESCUE_OFF	"rescue_off"
+#define USB_MODE_STATE_REQUEST	"mode_request"  /* returns the current mode */
+#define USB_MODE_RESCUE_OFF	"rescue_off"    /* turns rescue mode off so normal mode selection is restored */
 #define USB_MODE_CONFIG_GET	"get_config"	/* returns the mode set in the config */
 #define USB_MODE_LIST		"get_modes"	/* returns a comma-separated list of supported modes for ui's */
 
@@ -43,7 +51,10 @@
 #define USB_MODE_NETWORK_SET	"net_config"    /* set the network config in the config file */
 #define USB_MODE_NETWORK_GET	"get_net_config"    /* get the network config from the config file */
 
-/* state definitions for signals and method parameters */
+/**
+ * (Transient) states reported by "sig_usb_state_ind" that are not modes.
+ * These are only reported by the signal, and never returned by e.g. "mode_request".
+ **/
 #define USB_CONNECTED			"USB connected"
 #define USB_DISCONNECTED		"USB disconnected"
 #define USB_REALLY_DISCONNECT		"USB mode change in progress"

src/usb_moded-modes.h

@@ -21,6 +21,7 @@
 /* possible values for the mode, however only the first three can be set through the method call
    the others being internal only.
  */
+
 #define MODE_MASS_STORAGE       "mass_storage"
 #define MODE_CHARGING           "charging_only"
 #define MODE_CHARGING_FALLBACK  "charging_only_fallback"
@@ -33,3 +34,11 @@
 #define MODE_CONNECTION_SHARING "connection_sharing"
 #define MODE_DIAG		"qa_diag_mode"
 #define MODE_ADB		"adb_mode"
+
+/**
+ *
+ * MODE_CHARGING : user manually selected charging mode
+ * MODE_CHARGING_FALLBACK : mode selection is not done by the user so we fallback to a charging mode to get some power
+ * MODE_CHARGER : there is a dedicated charger connected to the USB port
+ *
+ **/