netdev - Re: critic on documentation of the network stack

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: <52E47E82.4040906@gmail.com>
Date:	Sat, 25 Jan 2014 19:18:26 -0800
From:	Florian Fainelli <f.fainelli@...il.com>
To:	Stephen Hemminger <stephen@...workplumber.org>,
	Hannes Frederic Sowa <hannes@...essinduktion.org>
CC:	netdev@...r.kernel.org
Subject: Re: critic on documentation of the network stack

Le 24/01/2014 15:58, Stephen Hemminger a écrit :
> On Fri, 24 Jan 2014 04:23:24 +0100
> Hannes Frederic Sowa <hannes@...essinduktion.org> wrote:
>
>> Hello!
>>
>> After net-next is closed I wanted to put the following link here:
>>
>>    <http://linux.slashdot.org/comments.pl?sid=4356053&cid=45184693>
>
> The problem I have is more that there are more incorrect sources of documentation
> and differing opinions on the Internet. Maybe the problem is users, maybe the
> problem is lack of SEO, or developers not being paid to write documentation, or
> old web sites not being updated. For example, this commenter obviously never
> found http://www.lartc.org/

(which unfortunately is rather outdated)

I do not buy the fact that some developers do not provide documentation 
of the features they are adding potentially on purpose, truth is 
probably much simpler, you worked on X, you have now moved on and work on Y.

If nobody pays enough attention to what gets added through netdev, 
iproute2, ethtool, man-pages and enforces the need for documentation, 
then comes the current status quo where not all features are documented, 
until some benevolant person realizes this needs fixing. Considering the 
high volume of the list, this is all understandable.

There could probably be some programmatical ways to enforce such 
documentation by only allowing patches coming with, say kernel-doc 
content along the code, and have man-pages and other projects scan for 
new kernel-doc entries they have no reference for.
--
Florian
--
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