Re: [Ksummit-discuss] [CORE-TOPIC] Documentation

[Randy Dunlap <rdunlap@infradead.org>]

On 07/13/15 02:47, Alexey Dobriyan wrote:
> On Mon, Jul 13, 2015 at 1:38 AM, Peter Hüwe <PeterHuewe@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,

I have no problem with that suggestion.  scripts/kernel-doc is fragile and
either needs lots of continuous help or can be discarded.

As I have said in the past, the main thing is that there should be decent
documentation for (new) interfaces.  It doesn't need to be kernel-doc.


> * 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).


-- 
~Randy