[PATCH -next v2] ACPI: Add kernel-doc comments for ACPI suspend and hibernation functions

[PATCH -next v2] ACPI: Add kernel-doc comments for ACPI suspend and hibernation functions

[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.

Signed-off-by: Yang Li <yang.lee@linux.alibaba.com>
---

change in v2:
--According to Randy's suggestion, use a space between '*'
  and function names, function parameters.

 drivers/acpi/sleep.c | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/drivers/acpi/sleep.c b/drivers/acpi/sleep.c
index 728acfeb774d..5bc61f40c189 100644
--- a/drivers/acpi/sleep.c
+++ b/drivers/acpi/sleep.c
@@ -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)
 {
-- 
2.20.1.7.g153144c

Re: [PATCH -next v2] ACPI: Add kernel-doc comments for ACPI suspend and hibernation functions

[Randy Dunlap]

On 3/14/24 17:37, Yang Li wrote:
> 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.
> 
> Signed-off-by: Yang Li <yang.lee@linux.alibaba.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
> 
> change in v2:
> --According to Randy's suggestion, use a space between '*'
>   and function names, function parameters.
> 
>  drivers/acpi/sleep.c | 24 ++++++++++++++----------
>  1 file changed, 14 insertions(+), 10 deletions(-)
> 

-- 
#Randy

Re: [PATCH -next v2] ACPI: Add kernel-doc comments for ACPI suspend and hibernation functions

[Rafael J. Wysocki]

On Fri, Mar 15, 2024 at 5:55 AM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
>
> On 3/14/24 17:37, Yang Li wrote:
> > 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.
> >
> > Signed-off-by: Yang Li <yang.lee@linux.alibaba.com>
>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

Applied as 6.9-rc material, thanks!