| Message ID | 20231206060144.8260-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | Accepted, archived |
| Headers | show |
| Series | platform/x86: thinkpad_acpi: fix kernel-doc warnings | expand |
Hi Randy 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 > 'tpacpi_check_quirks' > thinkpad_acpi.c:9307: warning: This comment starts with '/**', but > isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst > thinkpad_acpi.c:9307: warning: missing initial short description on > 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ärvinen" <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 > 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 field Just being nosy - what does %0 do? I assume it helps with the return value but was intrigued how it is used and where > 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 missing? > */ > 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 Thanks Mark
Hi Mark, On 12/6/23 07:30, Mark Pearson wrote: > Hi Randy > > 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 >> 'tpacpi_check_quirks' >> thinkpad_acpi.c:9307: warning: This comment starts with '/**', but >> isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst >> thinkpad_acpi.c:9307: warning: missing initial short description on >> 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ärvinen" <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 >> 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 field > > Just being nosy - what does %0 do? > I assume it helps with the return value but was intrigued how it is used and where It causes the output to be formatted as a CONSTANT (probably monospaced font, but no guarantees on that). > >> 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 missing? s/much/must/ > >> */ >> 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 > > Thanks > Mark
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 >> >> 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 >>> 'tpacpi_check_quirks' >>> thinkpad_acpi.c:9307: warning: This comment starts with '/**', but >>> isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst >>> thinkpad_acpi.c:9307: warning: missing initial short description on >>> 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ärvinen" <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 >>> 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 field >> >> Just being nosy - what does %0 do? >> I assume it helps with the return value but was intrigued how it is used and where > > It causes the output to be formatted as a CONSTANT (probably monospaced font, > but no guarantees on that). Ah - cool. Thanks! > >> >>> 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 missing? > > s/much/must/ Man....I need to go to the opticians :) > >> >>> */ >>> 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 >> >> Thanks >> Mark > > -- > ~Randy Looks good to me! Reviewed-by: mpearson-lenovo@squebb.ca Mark
On Tue, 05 Dec 2023 22:01:43 -0800, 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 'tpacpi_check_quirks' > thinkpad_acpi.c:9307: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst > thinkpad_acpi.c:9307: warning: missing initial short description on line: > * This evaluates a ACPI method call specific to the battery > > [...] Thank you for your contribution, it has been applied to my local review-ilpo branch. Note it will show up in the public platform-drivers-x86/review-ilpo branch only once I've pushed my local branch there, which might take a while. The list of commits applied: [1/1] platform/x86: thinkpad_acpi: fix kernel-doc warnings commit: 17fe3ec0c110b4afc04052e2a33b146766aac8a1 -- i.
diff -- a/drivers/platform/x86/thinkpad_acpi.c 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 field 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. */ 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.
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 'tpacpi_check_quirks' thinkpad_acpi.c:9307: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst thinkpad_acpi.c:9307: warning: missing initial short description on 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ärvinen" <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(-)