Re: [PATCH 24/45] CacheFiles: Add a hook to write a single page of data to an inode [ver #41]

[Randy Dunlap <randy.dunlap@oracle.com>]

David Howells wrote:
> Andrew Morton <akpm@linux-foundation.org> wrote:
> 
>> Sigh.  I don't normally comment on busted comment layout, but Ingo does
>> so I'm allowed to ;) See recent discussion around the kmemleak patches.
> 
> Sigh.  Three points for you to consider:
> 
>  (1) The prevailing comment style in struct address_space_operations does not
>      have comment delimiters on their own lines.  This has the advantage that
>      it doesn't unnecessarily waste two lines per comment.  I will advocate
>      that style for banner comments for top-level constructs, but for internal
>      comments it's generally a poor compromise.

I would have said that the prevailing comment style in struct
address_space_operations is sketchy or limited or lacking.

I want useful comments.  I don't give a hoot whether they are in kernel-doc
format or /* or //.  I'll even take them in a separate file if they are
more about theory of operation (overview) instead of directly related
to a struct or a function's operations, although some people want comments
only in source files because that is more likely to be updated when
needed.  I agree with that sentiment, but I wouldn't limit people to
having comments only in source files.  I just want comments or doc files
(which you usually provide plenty of).


>      The following comment on braces applies also to comments:
> 
> 	Also, note that this brace-placement also minimizes the number of empty
> 	(or almost empty) lines, without any loss of readability.  Thus, as the
> 	supply of new-lines on your screen is not a renewable resource (think
> 	25-line terminal screens here), you have more empty lines to put
> 	comments on.
> 
>  (2) Randy Dunlap should be beaten for his contribution to CodingStyle.  Next
>      time I have the opportunity, I'll do just that, and this time I'll see
>      about using one of my own racquets rather than one of his:-P

Bring it on.  and -ENOPATCH.

I don't own Documentation/CodingStyle. I'm just willing to send patches for it.
You (or anyone) can do the same.


>  (3) It's so much easier to write style guides than to properly document one's
>      code.

Easy to write a style guide, but difficult to get consensus on it.

If you don't document your own code, who will do it?  Probably nobody.


> </rant>
> 
>>> +/**
>>> + * generic_file_buffered_write_one_page - Write a single page of data to an
>>> + *	inode
>> kerneldoc doesn't permit line breaks in this context (unless it got
>> fixed recently)

No, it's not fixed.

> So you advocate a line exceeding 80 chars?

Either that or break the first line (function name & short description) up like:

/**
 * fubar - generally scrog and muck the system [based on an armed forces acronym for guess what]
 */

Change that to:

/**
 * fubar - scrog and muck up the system
 *
 * fubar (the name) is believed to come from an armed forces acronym
 * for you_know_what.
 */


> I contend that kerneldoc is a bad idea in many ways: it encourages people to
> be lazy and to not write proper interface documentation.

I can't/don't force you or anyone to write proper documentation, and the
maintainers who could do that don't do it.

But basically (see above), I just want documentation.  It's form is
not a big deal to me.  The good thing about kernel-doc is that it
provides some consistency.  Have you ever heard of look and feel?
Well, documentation can have consistent look and feel too, and it should.

Do we make exceptions?  Sure, we do.  Just look at Documentation/lguest/.


-- 
~Randy