| From a6f7306c0933fa6c5e5e707d5a87bf53fbefeef1 Mon Sep 17 00:00:00 2001 |
| From: "Rafael J. Wysocki" <rjw@sisk.pl> |
| Date: Mon, 13 Feb 2012 16:29:14 +0100 |
| Subject: PM / Sleep: Unify kerneldoc comments in kernel/power/suspend.c |
| |
| The kerneldoc comments in kernel/power/suspend.c are not formatted |
| in the same way and the quality of some of them is questionable. |
| Unify the formatting and improve the contents. |
| |
| Signed-off-by: Rafael J. Wysocki <rjw@sisk.pl> |
| Acked-by: Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com> |
| (cherry picked from commit 55ae451918ec62e553f11b6118fec157f90c31c3) |
| |
| Signed-off-by: Simon Horman <horms@verge.net.au> |
| --- |
| kernel/power/suspend.c | 56 +++++++++++++++++++++++-------------------------- |
| 1 file changed, 27 insertions(+), 29 deletions(-) |
| |
| --- a/kernel/power/suspend.c |
| +++ b/kernel/power/suspend.c |
| @@ -38,8 +38,8 @@ const char *const pm_states[PM_SUSPEND_M |
| static const struct platform_suspend_ops *suspend_ops; |
| |
| /** |
| - * suspend_set_ops - Set the global suspend method table. |
| - * @ops: Pointer to ops structure. |
| + * suspend_set_ops - Set the global suspend method table. |
| + * @ops: Suspend operations to use. |
| */ |
| void suspend_set_ops(const struct platform_suspend_ops *ops) |
| { |
| @@ -59,11 +59,11 @@ bool valid_state(suspend_state_t state) |
| } |
| |
| /** |
| - * suspend_valid_only_mem - generic memory-only valid callback |
| + * suspend_valid_only_mem - Generic memory-only valid callback. |
| * |
| - * Platform drivers that implement mem suspend only and only need |
| - * to check for that in their .valid callback can use this instead |
| - * of rolling their own .valid callback. |
| + * Platform drivers that implement mem suspend only and only need to check for |
| + * that in their .valid() callback can use this instead of rolling their own |
| + * .valid() callback. |
| */ |
| int suspend_valid_only_mem(suspend_state_t state) |
| { |
| @@ -84,10 +84,11 @@ static int suspend_test(int level) |
| } |
| |
| /** |
| - * suspend_prepare - Do prep work before entering low-power state. |
| + * suspend_prepare - Prepare for entering system sleep state. |
| * |
| - * This is common code that is called for each state that we're entering. |
| - * Run suspend notifiers, allocate a console and stop all processes. |
| + * Common code run for every system sleep state that can be entered (except for |
| + * hibernation). Run suspend notifiers, allocate the "suspend" console and |
| + * freeze processes. |
| */ |
| static int suspend_prepare(void) |
| { |
| @@ -132,9 +133,9 @@ void __attribute__ ((weak)) arch_suspend |
| } |
| |
| /** |
| - * suspend_enter - enter the desired system sleep state. |
| - * @state: State to enter |
| - * @wakeup: Returns information that suspend should not be entered again. |
| + * suspend_enter - Make the system enter the given sleep state. |
| + * @state: System sleep state to enter. |
| + * @wakeup: Returns information that the sleep state should not be re-entered. |
| * |
| * This function should be called after devices have been suspended. |
| */ |
| @@ -200,9 +201,8 @@ static int suspend_enter(suspend_state_t |
| } |
| |
| /** |
| - * suspend_devices_and_enter - suspend devices and enter the desired system |
| - * sleep state. |
| - * @state: state to enter |
| + * suspend_devices_and_enter - Suspend devices and enter system sleep state. |
| + * @state: System sleep state to enter. |
| */ |
| int suspend_devices_and_enter(suspend_state_t state) |
| { |
| @@ -254,10 +254,10 @@ int suspend_devices_and_enter(suspend_st |
| } |
| |
| /** |
| - * suspend_finish - Do final work before exiting suspend sequence. |
| + * suspend_finish - Clean up before finishing the suspend sequence. |
| * |
| - * Call platform code to clean up, restart processes, and free the |
| - * console that we've allocated. This is not called for suspend-to-disk. |
| + * Call platform code to clean up, restart processes, and free the console that |
| + * we've allocated. This routine is not called for hibernation. |
| */ |
| static void suspend_finish(void) |
| { |
| @@ -268,14 +268,12 @@ static void suspend_finish(void) |
| } |
| |
| /** |
| - * enter_state - Do common work of entering low-power state. |
| - * @state: pm_state structure for state we're entering. |
| + * enter_state - Do common work needed to enter system sleep state. |
| + * @state: System sleep state to enter. |
| * |
| - * Make sure we're the only ones trying to enter a sleep state. Fail |
| - * if someone has beat us to it, since we don't want anything weird to |
| - * happen when we wake up. |
| - * Then, do the setup for suspend, enter the state, and cleaup (after |
| - * we've woken up). |
| + * Make sure that no one else is trying to put the system into a sleep state. |
| + * Fail if that's not the case. Otherwise, prepare for system suspend, make the |
| + * system enter the given sleep state and clean up after wakeup. |
| */ |
| int enter_state(suspend_state_t state) |
| { |
| @@ -313,11 +311,11 @@ int enter_state(suspend_state_t state) |
| } |
| |
| /** |
| - * pm_suspend - Externally visible function for suspending system. |
| - * @state: Enumerated value of state to enter. |
| + * pm_suspend - Externally visible function for suspending the system. |
| + * @state: System sleep state to enter. |
| * |
| - * Determine whether or not value is within range, get state |
| - * structure, and enter (above). |
| + * Check if the value of @state represents one of the supported states, |
| + * execute enter_state() and update system suspend statistics. |
| */ |
| int pm_suspend(suspend_state_t state) |
| { |