Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.38 as permitted sender) client-ip=23.128.96.38;
Feedback-ID: ibe194615:Fastmail
User-Agent: Cyrus-JMAP/3.9.0-alpha0-1178-geeaf0069a7-fm-20231114.001-geeaf0069
MIME-Version: 1.0
Message-Id: <90220e8f-12e1-4b76-a438-f333fdedce9e@app.fastmail.com>
In-Reply-To: <f734ff9e-6005-4d47-959d-fab34c71c6e0@infradead.org>
References: <20231206060144.8260-1-rdunlap@infradead.org>
 <ea94a2d7-a13c-4f08-9979-48a8f33a47fc@app.fastmail.com>
 <f734ff9e-6005-4d47-959d-fab34c71c6e0@infradead.org>
Date:   Wed, 06 Dec 2023 11:48:44 -0500
From:   "Mark Pearson" <mpearson-lenovo@squebb.ca>
To:     "Randy Dunlap" <rdunlap@infradead.org>,
        linux-kernel@vger.kernel.org
Cc:     ibm-acpi-devel@lists.sourceforge.net,
        "platform-driver-x86@vger.kernel.org" 
        <platform-driver-x86@vger.kernel.org>,
        "Hans de Goede" <hdegoede@redhat.com>,
        "Henrique de Moraes Holschuh" <hmh@hmh.eng.br>,
        =?UTF-8?Q?Ilpo_J=C3=A4rvinen?= <ilpo.jarvinen@linux.intel.com>
Subject: Re: [ibm-acpi-devel] [PATCH] platform/x86: thinkpad_acpi: fix kernel-doc
 warnings
Content-Type: text/plain;charset=utf-8
Content-Transfer-Encoding: quoted-printable
Precedence: bulk


On Wed, Dec 6, 2023, at 11:45 AM, Randy Dunlap wrote:
> Hi Mark,
>
> On 12/6/23 07:30, Mark Pearson wrote:
>> Hi Randy
>>=20
>> On Wed, Dec 6, 2023, at 1:01 AM, Randy Dunlap wrote:
>>> Add a function's return description and don't misuse "/**" for
>>> non-kernel-doc comments to prevent warnings from scripts/kernel-doc.
>>>
>>> thinkpad_acpi.c:523: warning: No description found for return value =
of=20
>>> 'tpacpi_check_quirks'
>>> thinkpad_acpi.c:9307: warning: This comment starts with '/**', but=20
>>> isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc=
.rst
>>> thinkpad_acpi.c:9307: warning: missing initial short description on=20
>>> line:
>>>  * This evaluates a ACPI method call specific to the battery
>>>
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>> Cc: Henrique de Moraes Holschuh <hmh@hmh.eng.br>
>>> Cc: Hans de Goede <hdegoede@redhat.com>
>>> Cc: "Ilpo J=C3=A4rvinen" <ilpo.jarvinen@linux.intel.com>
>>> CC: ibm-acpi-devel@lists.sourceforge.net
>>> CC: platform-driver-x86@vger.kernel.org
>>> ---
>>>  drivers/platform/x86/thinkpad_acpi.c |    6 +++---
>>>  1 file changed, 3 insertions(+), 3 deletions(-)
>>>
>>> diff -- a/drivers/platform/x86/thinkpad_acpi.c=20
>>> b/drivers/platform/x86/thinkpad_acpi.c
>>> --- a/drivers/platform/x86/thinkpad_acpi.c
>>> +++ b/drivers/platform/x86/thinkpad_acpi.c
>>> @@ -512,10 +512,10 @@ struct tpacpi_quirk {
>>>   * Iterates over a quirks list until one is found that matches the
>>>   * ThinkPad's vendor, BIOS and EC model.
>>>   *
>>> - * Returns 0 if nothing matches, otherwise returns the quirks field=
 of
>>> + * Returns: %0 if nothing matches, otherwise returns the quirks fie=
ld=20
>>=20
>> Just being nosy - what does %0 do?
>> I assume it helps with the return value but was intrigued how it is u=
sed and where
>
> It causes the output to be formatted as a CONSTANT (probably monospace=
d font,
> but no guarantees on that).
Ah - cool. Thanks!
>
>>=20
>>> of
>>>   * the matching &struct tpacpi_quirk entry.
>>>   *
>>> - * The match criteria is: vendor, ec and bios much match.
>>> + * The match criteria is: vendor, ec and bios must match.
>> I can't for the life of me see what is different here. What am I miss=
ing?=20
>
> s/much/must/
Man....I need to go to the opticians :)

>
>>=20
>>>   */
>>>  static unsigned long __init tpacpi_check_quirks(
>>>  			const struct tpacpi_quirk *qlist,
>>> @@ -9303,7 +9303,7 @@ static struct tpacpi_battery_driver_data
>>>
>>>  /* ACPI helpers/functions/probes */
>>>
>>> -/**
>>> +/*
>>>   * This evaluates a ACPI method call specific to the battery
>>>   * ACPI extension. The specifics are that an error is marked
>>>   * in the 32rd bit of the response, so we just check that here.
>>>
>>>
>>> _______________________________________________
>>> ibm-acpi-devel mailing list
>>> ibm-acpi-devel@lists.sourceforge.net
>>> https://lists.sourceforge.net/lists/listinfo/ibm-acpi-devel
>>=20
>> Thanks
>> Mark
>
> --=20
> ~Randy

Looks good to me!=20
Reviewed-by: mpearson-lenovo@squebb.ca

Mark