Skip to contentSkip to conversation

ACPI: Add kernel-doc comments for ACPI suspend and hibernation functions

PATCH Superseded Yang Li 2 participants 2 messages Mar 8, 2024 ACPI

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Yang Li

author
#0 lore raw

PATCH 1/1 ACPI: Add kernel-doc comments for ACPI suspend and hibernation functions

This patch enhances the documentation for the ACPI power management functions related to system suspend and hibernation. This includes the use of kernel-doc style comments which provide developers with clearer guidance on the usage and expectations of these functions.

---
 drivers/acpi/sleep.c | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)
drivers/acpi/sleep.c +14 -10
index 728acfeb774d..5bc61f40c189 100644
@@ -502,6 +502,7 @@ static void acpi_pm_finish(void)
 
 /**
  * acpi_pm_start - Start system PM transition.
+ * @acpi_state: The target ACPI power state to transition to.
  */
 static void acpi_pm_start(u32 acpi_state)
 {
@@ -540,8 +541,9 @@ static u32 acpi_suspend_states[] = {
 };
 
 /**
- *	acpi_suspend_begin - Set the target system sleep state to the state
- *		associated with given @pm_state, if supported.
+ *acpi_suspend_begin - Set the target system sleep state to the state
+ *	associated with given @pm_state, if supported.
+ *@pm_state: The target system power management state.
  */
 static int acpi_suspend_begin(suspend_state_t pm_state)
 {
@@ -671,10 +673,11 @@ static const struct platform_suspend_ops acpi_suspend_ops = {
 };
 
 /**
- *	acpi_suspend_begin_old - Set the target system sleep state to the
- *		state associated with given @pm_state, if supported, and
- *		execute the _PTS control method.  This function is used if the
- *		pre-ACPI 2.0 suspend ordering has been requested.
+ *acpi_suspend_begin_old - Set the target system sleep state to the
+ *	state associated with given @pm_state, if supported, and
+ *	execute the _PTS control method.  This function is used if the
+ *	pre-ACPI 2.0 suspend ordering has been requested.
+ *@pm_state: The target suspend state for the system.
  */
 static int acpi_suspend_begin_old(suspend_state_t pm_state)
 {
@@ -967,10 +970,11 @@ static const struct platform_hibernation_ops acpi_hibernation_ops = {
 };
 
 /**
- *	acpi_hibernation_begin_old - Set the target system sleep state to
- *		ACPI_STATE_S4 and execute the _PTS control method.  This
- *		function is used if the pre-ACPI 2.0 suspend ordering has been
- *		requested.
+ *acpi_hibernation_begin_old - Set the target system sleep state to
+ *	ACPI_STATE_S4 and execute the _PTS control method.  This
+ *	function is used if the pre-ACPI 2.0 suspend ordering has been
+ *	requested.
+ *@stage: The power management event message.
  */
 static int acpi_hibernation_begin_old(pm_message_t stage)
 {
Signature · 1 line
2.20.1.7.g153144c
#1 lore raw

Hi--

Quoted 23 lines · Yang Li

This patch enhances the documentation for the ACPI power management functions related to system suspend and hibernation. This includes the use of kernel-doc style comments which provide developers with clearer guidance on the usage and expectations of these functions.

---
 drivers/acpi/sleep.c | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)
drivers/acpi/sleep.c +1 -0
index 728acfeb774d..5bc61f40c189 100644
@@ -502,6 +502,7 @@ static void acpi_pm_finish(void)
 
 /**
  * acpi_pm_start - Start system PM transition.
+ * @acpi_state: The target ACPI power state to transition to.
  */
 static void acpi_pm_start(u32 acpi_state)
 {

drivers/acpi/sleep.c static u32 acpi_suspend_states[] = { · line 546

Quoted 8 lines
drivers/acpi/sleep.c +3 -2
@@ -540,8 +541,9 @@ static u32 acpi_suspend_states[] = {
 };
 
 /**
- *	acpi_suspend_begin - Set the target system sleep state to the state
- *		associated with given @pm_state, if supported.
+ *acpi_suspend_begin - Set the target system sleep state to the state
+ *	associated with given @pm_state, if supported.
+ *@pm_state: The target system power management state.

Please use a space between '*' and function names, function parameters, etc.

Quoted 6 lines
drivers/acpi/sleep.c +0 -0
  */
 static int acpi_suspend_begin(suspend_state_t pm_state)
 {
@@ -671,10 +673,11 @@ static const struct platform_suspend_ops acpi_suspend_ops = {
 };
 

drivers/acpi/sleep.c static const struct platform_suspend_ops acpi_suspend_ops = { · line 680

Quoted 10 lines
drivers/acpi/sleep.c +5 -4
 /**
- *	acpi_suspend_begin_old - Set the target system sleep state to the
- *		state associated with given @pm_state, if supported, and
- *		execute the _PTS control method.  This function is used if the
- *		pre-ACPI 2.0 suspend ordering has been requested.
+ *acpi_suspend_begin_old - Set the target system sleep state to the
+ *	state associated with given @pm_state, if supported, and
+ *	execute the _PTS control method.  This function is used if the
+ *	pre-ACPI 2.0 suspend ordering has been requested.
+ *@pm_state: The target suspend state for the system.

Ditto.

Quoted 6 lines
drivers/acpi/sleep.c +0 -0
  */
 static int acpi_suspend_begin_old(suspend_state_t pm_state)
 {
@@ -967,10 +970,11 @@ static const struct platform_hibernation_ops acpi_hibernation_ops = {
 };
 

drivers/acpi/sleep.c static const struct platform_hibernation_ops acpi_hibernation_ops = { · line 977

Quoted 10 lines
drivers/acpi/sleep.c +5 -4
 /**
- *	acpi_hibernation_begin_old - Set the target system sleep state to
- *		ACPI_STATE_S4 and execute the _PTS control method.  This
- *		function is used if the pre-ACPI 2.0 suspend ordering has been
- *		requested.
+ *acpi_hibernation_begin_old - Set the target system sleep state to
+ *	ACPI_STATE_S4 and execute the _PTS control method.  This
+ *	function is used if the pre-ACPI 2.0 suspend ordering has been
+ *	requested.
+ *@stage: The power management event message.

Ditto.

drivers/acpi/sleep.c static const struct platform_hibernation_ops acpi_hibernation_ops = { · line 980

Quoted 3 lines
drivers/acpi/sleep.c +0 -0
  */
 static int acpi_hibernation_begin_old(pm_message_t stage)
 {

thanks.

Signature · 1 line
#Randy