RE: [PATCH] watchdog: fix syntactic kernel-doc issues
> On 3/21/21 11:53 PM, Lukas Bulwahn wrote:
> > The command 'find drivers/watchdog | xargs ./scripts/kernel-doc -none'
> > reports a number of kernel-doc warnings in the watchdog subsystem.
> >
> > Address the kernel-doc warnings that were purely syntactic issues with
> > kernel-doc comments.
> >
> > The remaining kernel-doc warnings are of type "Excess function
> parameter"
> > and "Function parameter or member not described". These warnings
> would
> > need to be addressed in a second pass with a bit more insight into the
> > APIs and purpose of the functions in the watchdog subsystem.
> >
> > Signed-off-by: Lukas Bulwahn
>
> Reviewed-by: Guenter Roeck
Ack for mei_wdt
Tomas
>
> > ---
> > Guenter, Wim, please pick this minor clean-up patch.
> >
> > drivers/watchdog/booke_wdt.c | 2 +-
> > drivers/watchdog/eurotechwdt.c | 2 +-
> > drivers/watchdog/mei_wdt.c | 8
> > drivers/watchdog/octeon-wdt-main.c | 12 +++-
> > drivers/watchdog/pc87413_wdt.c | 2 +-
> > drivers/watchdog/wdt.c | 4 ++--
> > drivers/watchdog/wdt_pci.c | 2 +-
> > 7 files changed, 17 insertions(+), 15 deletions(-)
> >
> > diff --git a/drivers/watchdog/booke_wdt.c
> > b/drivers/watchdog/booke_wdt.c index 7817fb976f9c..5e4dc1a0f2c6
> 100644
> > --- a/drivers/watchdog/booke_wdt.c
> > +++ b/drivers/watchdog/booke_wdt.c
> > @@ -148,7 +148,7 @@ static void __booke_wdt_enable(void *data) }
> >
> > /**
> > - * booke_wdt_disable - disable the watchdog on the given CPU
> > + * __booke_wdt_disable - disable the watchdog on the given CPU
> > *
> > * This function is called on each CPU. It disables the watchdog on that
> CPU.
> > *
> > diff --git a/drivers/watchdog/eurotechwdt.c
> > b/drivers/watchdog/eurotechwdt.c index 2418ebb707bd..ce682942662c
> > 100644
> > --- a/drivers/watchdog/eurotechwdt.c
> > +++ b/drivers/watchdog/eurotechwdt.c
> > @@ -392,7 +392,7 @@ static struct notifier_block eurwdt_notifier = {
> > };
> >
> > /**
> > - * cleanup_module:
> > + * eurwdt_exit:
> > *
> > * Unload the watchdog. You cannot do this with any file handles open.
> > * If your watchdog is set to continue ticking on close and you
> > unload diff --git a/drivers/watchdog/mei_wdt.c
> > b/drivers/watchdog/mei_wdt.c index e023d7d90d66..c7a7235e6224 100644
> > --- a/drivers/watchdog/mei_wdt.c
> > +++ b/drivers/watchdog/mei_wdt.c
> > @@ -105,7 +105,7 @@ struct mei_wdt {
> > #endif /* CONFIG_DEBUG_FS */
> > };
> >
> > -/*
> > +/**
> > * struct mei_mc_hdr - Management Control Command Header
> > *
> > * @command: Management Control (0x2) @@ -121,7 +121,7 @@ struct
> > mei_mc_hdr { };
> >
> > /**
> > - * struct mei_wdt_start_request watchdog start/ping
> > + * struct mei_wdt_start_request - watchdog start/ping
> > *
> > * @hdr: Management Control Command Header
> > * @timeout: timeout value
> > @@ -134,7 +134,7 @@ struct mei_wdt_start_request { } __packed;
> >
> > /**
> > - * struct mei_wdt_start_response watchdog start/ping response
> > + * struct mei_wdt_start_response - watchdog start/ping response
> > *
> > * @hdr: Management Control Command Header
> > * @status: operation status
> > @@ -474,7 +474,7 @@ static void mei_wdt_rx(struct mei_cl_device *cldev)
> > complete(>response);
> > }
> >
> > -/*
> > +/**
> > * mei_wdt_notif - callback for event notification
> > *
> > * @cldev: bus device
> > diff --git a/drivers/watchdog/octeon-wdt-main.c
> > b/drivers/watchdog/octeon-wdt-main.c
> > index fde9e739b436..298c070884c4 100644
> > --- a/drivers/watchdog/octeon-wdt-main.c
> > +++ b/drivers/watchdog/octeon-wdt-main.c
> > @@ -119,7 +119,7 @@ static int cpu2core(int cpu) }
> >
> > /**
> > - * Poke the watchdog when an interrupt is received
> > + * octeon_wdt_poke_irq - Poke the watchdog when an interrupt is
> > + received
> > *
> > * @cpl:
> > * @dev_id:
> > @@ -153,7 +153,7 @@ static irqreturn_t octeon_wdt_poke_irq(int cpl,
> > void *dev_id) extern int prom_putchar(char c);
> >
> > /**
> > - * Write a string to the uart
> > + * octeon_wdt_write_string - Write a string to the uart
> > *
> > * @str:String to write
> > */
> > @@ -165,7 +165,7 @@ static void octeon_wdt_write_string(const char
> > *str) }
> >
> > /**
> > - * Write a hex number out of the uart
> > + * octeon_wdt_write_hex() - Write a hex number out of the uart
> > *
> > * @value: Number to display
> > * @digits: Number of digits to print (1 to 16)
> > @@ -192,6 +192,8 @@ static const char reg_name[][3] = { };
> >
> > /**
> > + * octeon_wdt_nmi_stage3:
> > + *
> > * NMI stage 3 handler. NMIs are handled in the following manner:
> > * 1) The first NMI handler enables CVMSEG and transfers from
> > * the bootbus region into normal memory. It is careful to not @@
> > -513,7 +515,7 @@ static struct watchdog_device octeon_wdt = {
> >
> > static enum cpuhp_state octeon_wdt_online;
> > /**
> > - * Module/ driver initialization.
> > + *
Re: [PATCH] watchdog: fix syntactic kernel-doc issues
On 3/21/21 11:53 PM, Lukas Bulwahn wrote:
> The command 'find drivers/watchdog | xargs ./scripts/kernel-doc -none'
> reports a number of kernel-doc warnings in the watchdog subsystem.
>
> Address the kernel-doc warnings that were purely syntactic issues with
> kernel-doc comments.
>
> The remaining kernel-doc warnings are of type "Excess function parameter"
> and "Function parameter or member not described". These warnings would
> need to be addressed in a second pass with a bit more insight into the
> APIs and purpose of the functions in the watchdog subsystem.
>
> Signed-off-by: Lukas Bulwahn
Reviewed-by: Guenter Roeck
> ---
> Guenter, Wim, please pick this minor clean-up patch.
>
> drivers/watchdog/booke_wdt.c | 2 +-
> drivers/watchdog/eurotechwdt.c | 2 +-
> drivers/watchdog/mei_wdt.c | 8
> drivers/watchdog/octeon-wdt-main.c | 12 +++-
> drivers/watchdog/pc87413_wdt.c | 2 +-
> drivers/watchdog/wdt.c | 4 ++--
> drivers/watchdog/wdt_pci.c | 2 +-
> 7 files changed, 17 insertions(+), 15 deletions(-)
>
> diff --git a/drivers/watchdog/booke_wdt.c b/drivers/watchdog/booke_wdt.c
> index 7817fb976f9c..5e4dc1a0f2c6 100644
> --- a/drivers/watchdog/booke_wdt.c
> +++ b/drivers/watchdog/booke_wdt.c
> @@ -148,7 +148,7 @@ static void __booke_wdt_enable(void *data)
> }
>
> /**
> - * booke_wdt_disable - disable the watchdog on the given CPU
> + * __booke_wdt_disable - disable the watchdog on the given CPU
> *
> * This function is called on each CPU. It disables the watchdog on that
> CPU.
> *
> diff --git a/drivers/watchdog/eurotechwdt.c b/drivers/watchdog/eurotechwdt.c
> index 2418ebb707bd..ce682942662c 100644
> --- a/drivers/watchdog/eurotechwdt.c
> +++ b/drivers/watchdog/eurotechwdt.c
> @@ -392,7 +392,7 @@ static struct notifier_block eurwdt_notifier = {
> };
>
> /**
> - * cleanup_module:
> + * eurwdt_exit:
> *
> * Unload the watchdog. You cannot do this with any file handles open.
> * If your watchdog is set to continue ticking on close and you unload
> diff --git a/drivers/watchdog/mei_wdt.c b/drivers/watchdog/mei_wdt.c
> index e023d7d90d66..c7a7235e6224 100644
> --- a/drivers/watchdog/mei_wdt.c
> +++ b/drivers/watchdog/mei_wdt.c
> @@ -105,7 +105,7 @@ struct mei_wdt {
> #endif /* CONFIG_DEBUG_FS */
> };
>
> -/*
> +/**
> * struct mei_mc_hdr - Management Control Command Header
> *
> * @command: Management Control (0x2)
> @@ -121,7 +121,7 @@ struct mei_mc_hdr {
> };
>
> /**
> - * struct mei_wdt_start_request watchdog start/ping
> + * struct mei_wdt_start_request - watchdog start/ping
> *
> * @hdr: Management Control Command Header
> * @timeout: timeout value
> @@ -134,7 +134,7 @@ struct mei_wdt_start_request {
> } __packed;
>
> /**
> - * struct mei_wdt_start_response watchdog start/ping response
> + * struct mei_wdt_start_response - watchdog start/ping response
> *
> * @hdr: Management Control Command Header
> * @status: operation status
> @@ -474,7 +474,7 @@ static void mei_wdt_rx(struct mei_cl_device *cldev)
> complete(>response);
> }
>
> -/*
> +/**
> * mei_wdt_notif - callback for event notification
> *
> * @cldev: bus device
> diff --git a/drivers/watchdog/octeon-wdt-main.c
> b/drivers/watchdog/octeon-wdt-main.c
> index fde9e739b436..298c070884c4 100644
> --- a/drivers/watchdog/octeon-wdt-main.c
> +++ b/drivers/watchdog/octeon-wdt-main.c
> @@ -119,7 +119,7 @@ static int cpu2core(int cpu)
> }
>
> /**
> - * Poke the watchdog when an interrupt is received
> + * octeon_wdt_poke_irq - Poke the watchdog when an interrupt is received
> *
> * @cpl:
> * @dev_id:
> @@ -153,7 +153,7 @@ static irqreturn_t octeon_wdt_poke_irq(int cpl, void
> *dev_id)
> extern int prom_putchar(char c);
>
> /**
> - * Write a string to the uart
> + * octeon_wdt_write_string - Write a string to the uart
> *
> * @str:String to write
> */
> @@ -165,7 +165,7 @@ static void octeon_wdt_write_string(const char *str)
> }
>
> /**
> - * Write a hex number out of the uart
> + * octeon_wdt_write_hex() - Write a hex number out of the uart
> *
> * @value: Number to display
> * @digits: Number of digits to print (1 to 16)
> @@ -192,6 +192,8 @@ static const char reg_name[][3] = {
> };
>
> /**
> + * octeon_wdt_nmi_stage3:
> + *
> * NMI stage 3 handler. NMIs are handled in the following manner:
> * 1) The first NMI handler enables CVMSEG and transfers from
> * the bootbus region into normal memory. It is careful to not
> @@ -513,7 +515,7 @@ static struct watchdog_device octeon_wdt = {
>
> static enum cpuhp_state octeon_wdt_online;
> /**
> - * Module/ driver initialization.
> + * octeon_wdt_init - Module/ driver initialization.
> *
> * Returns Zero on success
> */
> @@ -585,7 +587,7 @@ static int __init octeon_wdt_init(void)
> }
>
> /**
> - * Module / driver shutdown
> + * octeon_wdt_cleanup - Module / driver shutdown
> */
> static void
