[PATCH] phylink: <linux/phylink.h>: fix function prototype kernel-doc warning

[PATCH] phylink: <linux/phylink.h>: fix function prototype kernel-doc warning

[Randy Dunlap]

Fix a kernel-doc warning for the pcs_config() function prototype:

../include/linux/phylink.h:406: warning: Excess function parameter 'permit_pause_to_mac' description in 'pcs_config'

Fixes: 7137e18f6f88 ("net: phylink: add struct phylink_pcs")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Russell King <linux@armlinux.org.uk>
Cc: David S. Miller <davem@davemloft.net>
Cc: netdev@vger.kernel.org
---
 include/linux/phylink.h |    3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

--- lnx-59-rc1.orig/include/linux/phylink.h
+++ lnx-59-rc1/include/linux/phylink.h
@@ -402,7 +402,8 @@ void pcs_get_state(struct phylink_pcs *p
  * For most 10GBASE-R, there is no advertisement.
  */
 int pcs_config(struct phylink_pcs *pcs, unsigned int mode,
-	       phy_interface_t interface, const unsigned long *advertising);
+	       phy_interface_t interface, const unsigned long *advertising,
+	       bool permit_pause_to_mac);
 
 /**
  * pcs_an_restart() - restart 802.3z BaseX autonegotiation

Re: [PATCH] phylink: <linux/phylink.h>: fix function prototype kernel-doc warning

[David Miller]

From: Randy Dunlap <rdunlap@infradead.org>
Date: Sun, 16 Aug 2020 15:25:49 -0700

> Fix a kernel-doc warning for the pcs_config() function prototype:
> 
> ../include/linux/phylink.h:406: warning: Excess function parameter 'permit_pause_to_mac' description in 'pcs_config'
> 
> Fixes: 7137e18f6f88 ("net: phylink: add struct phylink_pcs")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>

There's no definition of this function anywhere.  Maybe just remove all of
this?

Re: [PATCH] phylink: <linux/phylink.h>: fix function prototype kernel-doc warning

[Randy Dunlap]

On 8/16/20 9:14 PM, David Miller wrote:
> From: Randy Dunlap <rdunlap@infradead.org>
> Date: Sun, 16 Aug 2020 15:25:49 -0700
> 
>> Fix a kernel-doc warning for the pcs_config() function prototype:
>>
>> ../include/linux/phylink.h:406: warning: Excess function parameter 'permit_pause_to_mac' description in 'pcs_config'
>>
>> Fixes: 7137e18f6f88 ("net: phylink: add struct phylink_pcs")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> 
> There's no definition of this function anywhere.  Maybe just remove all of
> this?
> 

It's for documentation purposes...

It's a "method" (callback) function.

-- 
~Randy

Re: [PATCH] phylink: <linux/phylink.h>: fix function prototype kernel-doc warning

[Russell King - ARM Linux admin]

On Sun, Aug 16, 2020 at 09:14:51PM -0700, David Miller wrote:
> From: Randy Dunlap <rdunlap@infradead.org>
> Date: Sun, 16 Aug 2020 15:25:49 -0700
> 
> > Fix a kernel-doc warning for the pcs_config() function prototype:
> > 
> > ../include/linux/phylink.h:406: warning: Excess function parameter 'permit_pause_to_mac' description in 'pcs_config'
> > 
> > Fixes: 7137e18f6f88 ("net: phylink: add struct phylink_pcs")
> > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> 
> There's no definition of this function anywhere.  Maybe just remove all of
> this?

This is kerneldoc documentation for the PCS methods - there's no other
way to document the method parameters than to use "fake" function
prototypes.

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 40Mbps down 10Mbps up. Decent connectivity at last!

Re: [PATCH] phylink: <linux/phylink.h>: fix function prototype kernel-doc warning

[David Miller]

From: Randy Dunlap <rdunlap@infradead.org>
Date: Sun, 16 Aug 2020 22:43:54 -0700

> On 8/16/20 9:14 PM, David Miller wrote:
>> From: Randy Dunlap <rdunlap@infradead.org>
>> Date: Sun, 16 Aug 2020 15:25:49 -0700
>> 
>>> Fix a kernel-doc warning for the pcs_config() function prototype:
>>>
>>> ../include/linux/phylink.h:406: warning: Excess function parameter 'permit_pause_to_mac' description in 'pcs_config'
>>>
>>> Fixes: 7137e18f6f88 ("net: phylink: add struct phylink_pcs")
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> 
>> There's no definition of this function anywhere.  Maybe just remove all of
>> this?
>> 
> 
> It's for documentation purposes...
> 
> It's a "method" (callback) function.

I see, that's an unfortunate shortcoming of kerneldoc.

Applied, thanks.