Re: [PATCH net-next v4 02/12] net: ethernet: oa_tc6: implement register write operation

[Parthiban.Veerasooran]

Hi Andrew,

On 23/04/24 5:18 am, Andrew Lunn wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
>> +/**
>> + * oa_tc6_write_registers - function for writing multiple consecutive registers.
>> + * @tc6: oa_tc6 struct.
>> + * @address: address of the first register to be written in the MAC-PHY.
>> + * @value: values to be written from the starting register address @address.
>> + * @length: number of consecutive registers to be written from @address.
>> + *
>> + * Maximum of 128 consecutive registers can be written starting at @address.
>> + *
>> + * Returns 0 on success otherwise failed.
>> + */
> 
OK. In this case kernel-doc tool takes it as **Description** that's why 
didn't complaint any error when I run the below command,

$ scripts/kernel-doc -v -none drivers/net/ethernet/oa_tc6.c

drivers/net/ethernet/oa_tc6.c:313: info: Scanning doc for function 
oa_tc6_read_registers
drivers/net/ethernet/oa_tc6.c:343: info: Scanning doc for function 
oa_tc6_read_register
drivers/net/ethernet/oa_tc6.c:357: info: Scanning doc for function 
oa_tc6_write_registers
drivers/net/ethernet/oa_tc6.c:387: info: Scanning doc for function 
oa_tc6_write_register
drivers/net/ethernet/oa_tc6.c:1154: info: Scanning doc for function 
oa_tc6_start_xmit
drivers/net/ethernet/oa_tc6.c:1185: info: Scanning doc for function 
oa_tc6_init
drivers/net/ethernet/oa_tc6.c:1306: info: Scanning doc for function 
oa_tc6_exit

Got this info from below link,

https://elixir.bootlin.com/linux/latest/source/Documentation/doc-guide/kernel-doc.rst#L53

https://elixir.bootlin.com/linux/latest/source/Documentation/doc-guide/kernel-doc.rst#L81

> I think the static analyser tools are getting more picky, and what
> 'Return:' .
> 
> https://elixir.bootlin.com/linux/latest/source/Documentation/doc-guide/kernel-doc.rst#L86
> 
> All the examples use Return:
OK. Thanks for the info. I will change it and also in other APIs as well 
in the next version.

Ex:
Return: 0 on success otherwise failed.
> 
> That document also says:
> 
> The documentation format is verified by the kernel build when it is
> requested to perform extra gcc checks::
> 
>          make W=n
Unfortunately it didn't complaint anything as "Returns" line considered 
as **Description** I guess.
> 
> And if patchwork can apply your patches, it also checks for problems
> like this.
OK. If I understand this correctly the above change will resolve this.

Best regards,
Parthiban V
> 
>      Andrew