Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
MIME-Version: 1.0
References: <20210610074812.57973-1-chenxiaosong2@huawei.com>
In-Reply-To: <20210610074812.57973-1-chenxiaosong2@huawei.com>
From:   "Rafael J. Wysocki" <rafael@kernel.org>
Date:   Mon, 14 Jun 2021 17:03:00 +0200
Message-ID: <CAJZ5v0j6S4DxuNiN_VeZQ1hc8kAMJ4oz7-P=PmR4OnsN0PEURw@mail.gmail.com>
Subject: Re: [PATCH -next] ACPI: fix doc warnings
To:     ChenXiaoSong <chenxiaosong2@huawei.com>
Cc:     "Rafael J. Wysocki" <rjw@rjwysocki.net>,
        Len Brown <lenb@kernel.org>,
        ACPI Devel Maling List <linux-acpi@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        yu kuai <yukuai3@huawei.com>, yi.zhang@huawei.com
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Thu, Jun 10, 2021 at 9:41 AM ChenXiaoSong <chenxiaosong2@huawei.com> wrote:
>
> Fix gcc W=1 warnings:
> drivers/acpi/cppc_acpi.c:1356: warning: Function parameter or member 'cpu_num' not described in 'cppc_get_transition_latency'
> drivers/acpi/cppc_acpi.c:573: warning: Function parameter or member 'pcc_ss_id' not described in 'pcc_data_alloc'
> drivers/acpi/dock.c:388: warning: Function parameter or member 'ds' not described in 'handle_eject_request'
> drivers/acpi/dock.c:388: warning: Function parameter or member 'event' not described in 'handle_eject_request'
> drivers/acpi/sleep.c:496: warning: Function parameter or member 'acpi_state' not described in 'acpi_pm_start'
> drivers/acpi/sleep.c:536: warning: Function parameter or member 'pm_state' not described in 'acpi_suspend_begin'
> drivers/acpi/sleep.c:663: warning: Function parameter or member 'pm_state' not described in 'acpi_suspend_begin_old'
> drivers/acpi/sleep.c:956: warning: Function parameter or member 'stage' not described in 'acpi_hibernation_begin_old'
>
> Signed-off-by: ChenXiaoSong <chenxiaosong2@huawei.com>
> ---
>  drivers/acpi/cppc_acpi.c | 2 ++
>  drivers/acpi/dock.c      | 2 ++
>  drivers/acpi/sleep.c     | 4 ++++
>  3 files changed, 8 insertions(+)
>
> diff --git a/drivers/acpi/cppc_acpi.c b/drivers/acpi/cppc_acpi.c
> index a4d4eebba1da..611938f2c132 100644
> --- a/drivers/acpi/cppc_acpi.c
> +++ b/drivers/acpi/cppc_acpi.c
> @@ -561,6 +561,7 @@ bool __weak cpc_ffh_supported(void)
>
>  /**
>   * pcc_data_alloc() - Allocate the pcc_data memory for pcc subspace
> + * @pcc_ss_id: pcc subspace id.
>   *
>   * Check and allocate the cppc_pcc_data memory.
>   * In some processor configurations it is possible that same subspace
> @@ -1346,6 +1347,7 @@ EXPORT_SYMBOL_GPL(cppc_set_perf);
>
>  /**
>   * cppc_get_transition_latency - returns frequency transition latency in ns
> + * @cpu: CPU for which to get transition latency.
>   *
>   * ACPI CPPC does not explicitly specify how a platform can specify the
>   * transition latency for performance change requests. The closest we have
> diff --git a/drivers/acpi/dock.c b/drivers/acpi/dock.c
> index 7cf92158008f..6c0fb5c9b938 100644
> --- a/drivers/acpi/dock.c
> +++ b/drivers/acpi/dock.c
> @@ -380,6 +380,8 @@ static int dock_in_progress(struct dock_station *ds)
>
>  /**
>   * handle_eject_request - handle an undock request checking for error conditions
> + * @ds: the dock station.
> + * @event: Event code.
>   *
>   * Check to make sure the dock device is still present, then undock and
>   * hotremove all the devices that may need removing.
> diff --git a/drivers/acpi/sleep.c b/drivers/acpi/sleep.c
> index aaea10d39201..95521a8b49fc 100644
> --- a/drivers/acpi/sleep.c
> +++ b/drivers/acpi/sleep.c
> @@ -491,6 +491,7 @@ static void acpi_pm_finish(void)
>
>  /**
>   * acpi_pm_start - Start system PM transition.
> + * @acpi_state: Power state value.
>   */
>  static void acpi_pm_start(u32 acpi_state)
>  {
> @@ -531,6 +532,7 @@ static u32 acpi_suspend_states[] = {
>  /**
>   *     acpi_suspend_begin - Set the target system sleep state to the state
>   *             associated with given @pm_state, if supported.
> + *     @pm_state: pm suspend state.

Well, I appreciate the effort, but this change doesn't really improve
the kerneldoc too much regarding the information provided by it.

In fact, @pm_state is documented already here, you just need to
rearrange this comment.

>   */
>  static int acpi_suspend_begin(suspend_state_t pm_state)
>  {
> @@ -658,6 +660,7 @@ static const struct platform_suspend_ops acpi_suspend_ops = {
>   *             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: pm suspend state.

Pretty much same as above.

>   */
>  static int acpi_suspend_begin_old(suspend_state_t pm_state)
>  {
> @@ -951,6 +954,7 @@ static const struct platform_hibernation_ops acpi_hibernation_ops = {
>   *             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: pm event massage

And here too.

>   */
>  static int acpi_hibernation_begin_old(pm_message_t stage)
>  {
> --
> 2.25.4
>