Randy Dunlap <randy.dunlap@xxxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
