[Ksummit-discuss] [CORE-TOPIC] Documentation

[Alexey Dobriyan]

On Mon, Jul 13, 2015 at 1:38 AM, Peter Hüwe <PeterHuewe at gmx.de> wrote:
> as we talked about recruiting in the other thread I realized that one thing
> that might reduce the entrance barrier a bit (apart from tooling and flow)
> would be proper documentation.

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:

    /**
     * is_module_percpu_address - test whether address is from module
static percpu
     * @addr: address to test
     *
     * Test whether @addr belongs to module static percpu area.
     *
     * RETURNS:
     * %true if @addr is from module static percpu area
     */

    bool is_module_percpu_address(unsigned long addr)
    {

I have counter suggestion:
* remove kernel-doc official status, remove generating scripts
  because it doesn't work,
* trim redundant and semi-redundant kernel-doc comments like this:

    /**
     * module_refcount - return the refcount or -1 if unloading
     *
     * @mod:        the module we're checking
     *
     * Returns:
     *      -1 if the module is in the process of unloading
     *      otherwise the number of references in the kernel to the module
     */
    int module_refcount(struct module *mod)
    {

("return reference count or -1 if module is being unloaded" is enough here).

      Alexey