On Sun, 02 Oct 2011 01:21:18 +0200 Aapo Laine <aapo.laine@xxxxxxxxxxxxx> wrote: > >> - it's not clear what the various functions do or in what occasion they > >> are called. Except from their own name, most of them have no comments > >> just before the definition. > > How about this: > > - you identify some functions for which the purpose or use isn't clear > > - I'll explain to you when/how/why they are used > > - You create a patch which adds comments which explains it all > > - I'll apply that patch. > > > > deal?? > > I would never dare to commit your comments back to you with my name, not > even if you ask me to do so :-) There is absolutely nothing wrong with taking someones work, adding value, and contributing it. You would obviously give credit to the original author. This is was open/free licensing is all about. There is a big difference between an answer to a question and piece of clear coherent documentation. The later can certainly use text from the former, but it also involves thinking about what documentation is needed, where to put it, how to present it etc. There is real value in doing that. > > But thanks for offering to explain the things. > If you do this on the mailing list everybody is going to read that and > this will be useful to everybody. > > Actually we could even open a new mailing list or maybe there is > something better in web 2.0, like a wiki, for these MD code > explanations. Explanations in a wiki can be longer, there can be user > discussions, and such lines of comments do not need to be pushed as far > as Linus. http://raid.wiki.kernel.org might be an appropriate place ... once kernel.org is fully functional again. One of the problems with documentation is that it quickly goes out of date. The best chance of keeping it up-to-date is to have it in the source tree with the code. > > >> - last but not least, variables have very short names, and for most of > >> them, it is not explained what they mean. This is mostly for local > >> variables, but sometimes even for the structs which go into metadata > >> e.g. in struct r1_private_data_s most members do not have an > >> explanation. This is pretty serious, to me at least, for understanding > >> the code. > > Does this help? > > > > diff --git a/drivers/md/raid1.h b/drivers/md/raid1.h .... > > YES! > thanks I've added that patch to my queue - it should go through in the next merge window. NeilBrown
Attachment:
signature.asc
Description: PGP signature
