Re: critic on documentation of the network stack

[Florian Fainelli <f.fainelli@gmail.com>]

Le 24/01/2014 15:58, Stephen Hemminger a écrit :
> On Fri, 24 Jan 2014 04:23:24 +0100
> Hannes Frederic Sowa <hannes@stressinduktion.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