Doxygen docs

Open-webOS-DCO-1.0-Signed-off-by: Kyle Maas <kylemaasdev@gmail.com>
Open-webOS-DCO-1.0-Signed-off-by: Keith Derrick <keith.derrick@lge.com>

src/main.c

@@ -17,6 +17,53 @@
 * LICENSE@@@ */
 
 
+/**
+ * @mainpage sleepd
+ * 
+ * @section summary Summary
+ * 
+ * Open webOS component to manage device suspend-resume cycles.
+ * 
+ * @section description Description
+ * 
+ * Sleepd is one of the important daemons started when webOS boots. It is
+ * responsible for scheduling platform sleeps as soon as it is idle, so that we
+ * see optimum battery performance. To achieve this it keeps polling on the
+ * system to see if any of the other services or processes need the platform
+ * running, and if not it sends the suspend message to all these components (so
+ * that they can finish whatever they are doing ASAP and suspend). Sleepd then
+ * lets the kernel know that the platform is ready to sleep. Once an interrupt
+ * (such as key press) has woken the platform up, sleepd lets the entire system
+ * know that the platform is up and running so that all the activities can
+ * resume.
+ * 
+ * Sleepd also manages the RTC alarms on the system by maintaining a SQlite
+ * database for all the requested alarms.
+ * 
+ * @section code-organization Code Organization
+ * 
+ * The code for sleepd is organized into two main categories:
+ * 
+ * - A bunch of individual power watcher modules which tie into the service bus
+ *   and react to IPC messages passed in and/or which start their own threads
+ *   and run separately.
+ * 
+ * - A central module initialization system which ties them all together and
+ *   handles all of the bookkeeping to keep them all running and gracefully shut
+ *   them down when the sleepd service is asked to stop.
+ * 
+ * Documentation for each of the power management modules is available in the
+ * section to the left entitled "Modules".
+ * 
+ * The modules each register themselves with the main initialization code using
+ * a macro called {@link INIT_FUNC}.  It uses GCC-specific functionality to
+ * run hook registration code when the binary is being loaded into memory.  As a
+ * result, all of the code to register these hooks is run before {@link main()}
+ * is called.  This creates a very modular code organizational approach in which
+ * new power saving modules can be added independently of the main
+ * initialization system.
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <signal.h>
@@ -42,6 +89,9 @@ bool ChargerStatus(LSHandle *sh,LSMessage *message, void *user_data); // defined
 
 #define LOG_DOMAIN "SLEEPD-INIT: "
 
+/**
+ * Handle process signals asking us to terminate running of our service
+ */
 void
 term_handler(int signal)
 {
@@ -75,6 +125,30 @@ GetNyxSystemDevice(void)
 	return nyxSystem;
 }
 
+/**
+ * Main entry point for sleepd - runs the initialization hooks installed at program load time
+ * 
+ * A bit counter-intuitively, this is not the first part of this program which
+ * is run.
+ * 
+ * First, everything which uses the {@link INIT_FUNC} macro in init.h are run,
+ * which registers a bunch of hooks with the initialization system so that
+ * individual modules can be registered without touching the main sleepd
+ * initialization code.  Then, once all of those hooks are installed, execution
+ * proceeds to this function which actually runs those hooks.
+ * 
+ * - Initializes sleepd.
+ * - Attaches as a Luna service under com.palm.sleep.
+ * - Attaches to Nyx.
+ * - Subscribes to events related to the charger being plugged and unplugged from the com.palm.power service.
+ * - Calls {@link TheOneInit()} to finish initialization of the service.
+ * - Issues a request to the com.palm.power service to check on the plugged/unplugged status of the charger.
+ * 
+ * @param	argc		Number of command-line arguments.
+ * @param	argv		List of command-line arguments.
+ * 
+ * @todo Move the logging initialization functionality into {@link TheOneInit()}.
+ */
 int
 main(int argc, char **argv)
 {
@@ -84,6 +158,10 @@ main(int argc, char **argv)
     LOGInit();
     LOGSetHandler(LOGSyslog);
 
+    /*
+     * Register a function to be able to gracefully handle termination signals
+     * from the OS or other processes.
+     */
     signal(SIGTERM, term_handler);
     signal(SIGINT, term_handler);
 
@@ -93,34 +171,51 @@ main(int argc, char **argv)
 
     mainloop = g_main_loop_new(NULL, FALSE);
 
-    /**
+    /*
      *  initialize the lunaservice and we want it before all the init
      *  stuff happening.
      */
     LSError lserror;
     LSErrorInit(&lserror);
 
+    /*
+     * Register ourselves as the com.palm.sleep service.
+     */
     retVal = LSRegisterPalmService("com.palm.sleep", &psh, &lserror);
     if (!retVal)
     {
         goto ls_error;
     }
 
+    /*
+     * Attach our main loop to the service so we can process IPC messages addressed to us.
+     */
     retVal = LSGmainAttachPalmService(psh, mainloop, &lserror);
     if (!retVal)
     {
         goto ls_error;
     }
 
+    /*
+     * Get our private bus for our service so we can pass a message to com.palm.power.
+     */
     private_sh = LSPalmServiceGetPrivateConnection(psh);
 
+    /*
+     * Register with com.palm.power for events regarding changes in status
+     * to the plug/unplug state of any chargers which may be attached to our
+     * device.
+     */
     retVal = LSCall(private_sh,"luna://com.palm.lunabus/signal/addmatch","{\"category\":\"/com/palm/power\","
               "\"method\":\"USBDockStatus\"}", ChargerStatus, NULL, NULL, &lserror);
     if (!retVal) {
 		SLEEPDLOG(LOG_CRIT,"Error in registering for luna-signal \"chargerStatus\"");
 		goto ls_error;
 	}
 
+    /*
+     * Connect to Nyx so we can use it later.
+     */
  	int ret = nyx_device_open(NYX_DEVICE_SYSTEM, "Main", &nyxSystem);
  	if(ret != NYX_ERROR_NONE)
  	{
@@ -129,8 +224,16 @@ main(int argc, char **argv)
  	}
 
 
+    /*
+     * Call our main initialization function - this is the function which
+     * is supposed to handle initializing pretty much everything for us.
+     */
     TheOneInit();
 
+    /*
+     * Now that we've got something listening for charger status changes,
+     * request the current state of the charger from com.palm.power.
+     */
  	LSCall(private_sh,"luna://com.palm.power/com/palm/power/chargerStatusQuery","{}",ChargerStatus,NULL,NULL,&lserror);
 
     SLEEPDLOG(LOG_INFO,"Sleepd daemon started\n");

src/pwrevents/machine.c

@@ -46,7 +46,20 @@
 
 static char *machineName = NULL;
 
-bool chargerIsConnected = false, usbconn = false, dockconn = false;
+/**
+ * Holds the current state of whether or not we're being supplied with power from a charger of any sort.
+ */
+bool chargerIsConnected = false;
+
+/**
+ * Holds the current state of whether or not we're being supplied with power from a USB charger.
+ */
+bool usbconn = false;
+
+/**
+ * Holds the current state of whether or not we're being supplied with power from a dock charger.
+ */
+bool dockconn = false;
 
 /**
  * Obtains the machine specific release name.
@@ -214,6 +227,35 @@ MachineGetToken(const char *token_name, char *buf, int len)
     return 0;
 }
 
+/**
+ * Handler for events from com.palm.power telling us when the charger is plugged/unplugged
+ * 
+ * This function is registered with the com.palm.power service in {@link main()}
+ * to allow us to track the state of the charger and adjust our power plan
+ * accordingly.
+ * 
+ * The "message" parameter will be given to us as a JSON object formatted as
+ * follows:
+ * 
+ * <code>
+ * {
+ *   "Charging" : {
+ *       "USBConnected" : true || false, //whether power is currently being supplied via a USB charger
+ *       "DockPower" : true || false //whether power is currently being supplied via a dock
+ *     }
+ * }
+ * </code>
+ * 
+ * {@link chargerIsConnected} will be changed in response to this message to
+ * indicate the current state of charging.  If power is being supplied to us
+ * by either charging method, {@link chargerIsConnected} is set to true.
+ * 
+ * @param	sh		Pointer to service handle.
+ * @param	message		JSON message which contains the latest information about the state of methods of charging.
+ * @param	user_data	Currently unused.
+ * 
+ * @return			Always returns true.
+ */
 bool ChargerStatus(LSHandle *sh,
                    LSMessage *message, void *user_data)
 {

src/utils/init.c

@@ -135,7 +135,12 @@ PrintHookLists(void)
 }
 
 /**
- * Instantiates all the 
+ * Runs all of the initialization hooks
+ * 
+ * This function runs all of the initialization functions which are preloaded
+ * into our {@link namedInitFuncs} array via the use of the {@link INIT_FUNC}
+ * macro using some GCC-specific functionality which runs code to install the
+ * hooks as the sleepd binary is loaded from disk.
  */
 void
 TheOneInit(void)