[Ksummit-discuss] [CORE-TOPIC] Documentation

[Steven Rostedt]

On Mon, 13 Jul 2015 12:47:23 +0300
Alexey Dobriyan <adobriyan at gmail.com> wrote:


> Newbies should not write documentation because they, by definition,
> have little knowledge of the code. It will lead to many, many useless
> and redundant comments like below whose only purpose is stealing
> vertical whitespace:

I agree that newbies shouldn't write documentation. But maybe what they
can do is to question what a function does. And perhaps poke the
maintainer (or author of said function) to write something that
explains that function (only for non-static functions).

Now, I say "newbies" but I would really mean experienced developers
that are new to a subsystem. We don't need silly questions. Something
more on the line of one experienced kernel developer reading some code
of the kernel they have no idea about, and if they can't figure out
what a function does, ask the question to the author. Perhaps we can
get better documentation of internal interfaces out of it.

There's been times where I look at other subsystems and wonder WTF a
function is suppose to do. Perhaps I need to start poking the author of
that code to explain it.

-- Steve