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

[David Howells <dhowells@redhat.com>]

Randy Dunlap <randy.dunlap@oracle.com> wrote:

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

Well, there's that too.

> 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 want to see proper interface documentation in Documentation.  Where an
interface is treated as a process, and where it's viewed from both sides where
others are expected both to implement it and to use it.

My opinion is that you should document any interface you propose on the theory
that if you can't explain your interface, why should you expect anyone to
understand what it does?

If I get some spare time, I intend to start writing it for interfaces that
already exist but don't have it yet.  It would then have to be up to those
that accept patches, from Linus on down, to force people to update
documentation when they submit a patch to alter, extend, add or remove an
interface.  Unfortunately, I don't see that as being likely to happen:-(

Sorry, but this is one of my favourite rants.

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

I do document my own code.  It's my responsibility to do so.

> Well, documentation can have consistent look and feel too, and it should.

Indeed.

David