netdev - Re: [PATCH 1/3] driver/net/*: remove redundant argument comments

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <9929d2390811212355j635e0e8iee0e53678efc5f09@mail.gmail.com>
Date:	Fri, 21 Nov 2008 23:55:27 -0800
From:	"Jeff Kirsher" <jeffrey.t.kirsher@...el.com>
To:	"Qinghuang Feng" <qhfeng.kernel@...il.com>
Cc:	"David Miller" <davem@...emloft.net>, netdev@...r.kernel.org,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH 1/3] driver/net/*: remove redundant argument comments

On Fri, Nov 21, 2008 at 11:40 PM, Qinghuang Feng
<qhfeng.kernel@...il.com> wrote:
> remove redundant argument comments in files of drivers/net/*
>
> Signed-off-by: Qinghuang Feng <qhfeng.kernel@...il.com>
> ---
> diff --git a/drivers/net/e1000e/netdev.c b/drivers/net/e1000e/netdev.c
> index 91795f7..122539a 100644
> --- a/drivers/net/e1000e/netdev.c
> +++ b/drivers/net/e1000e/netdev.c
> @@ -345,7 +345,6 @@ no_buffers:
>  /**
>  * e1000_alloc_jumbo_rx_buffers - Replace used jumbo receive buffers
>  * @adapter: address of board private structure
> - * @rx_ring: pointer to receive ring structure
>  * @cleaned_count: number of buffers to allocate this pass
>  **/
>

NAK - rather than removing documentation, I would suggest improving
the documentation.  Your suggested patch removes lines in the function
headers which can be (if not already) in documentation.  Specifically,
the function header comments for Intel drivers was written in such a
way that it can be parsed out by the kernel documentation scripts to
create an API document.

I would agree that "@rx_ring: pointer to receive ring structure" is
probably not the best documentation, but rather than removing it, I
would suggest improving it.


-- 
Cheers,
Jeff
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html