Messages in this thread | | | From | "Kevin M. Bealer" <> | Subject | Re: Take A deep Breath - Kernel Documentation | Date | Sun, 20 Jul 1997 17:34:36 -0400 |
| |
Dietmar Kling wrote: >> do you mean something like javadoc? you run the source thourough >> and it makes doumentation? > >No, i think it's not good to have the source full of comments (they _are_ useful, agreed!) , there sho >uld be some kind of outside documentation. > (clip)
I would agree with this. Code comments should not contain large scale documentation for a number of reasons:
1. If the coder or documenter wants to update their code, they cannot do so seperately, it would have to be coordinated a lot. Linus should not have to handle integrating all the documentation, he has enough to do with the code.
2. Documentation will always be a little out of sync, anyone who experiments a lot with code knows you can't keep it up to date for each tweak. If it is in a seperate file, it can be kept coordinated and also versioning would be seperate.
3. Obvious kernel tarball size arguments. (Imagine the traffic..) Likewise there should be a seperate discussion list.
..i could go on..
>But, > >1. WE NEED A KIND OF STYLE GUIDE FOR DOCUMENTATION!
The documentation could probably be laid out in a format similar to the layout of the kernel. That way if you want to document something you know immediately if it is documented. There would be other files which would give general info, overviews, etc.
Probably something like:
Table of contents (one line about each function/structure defined).
Overview: Context: Talk about relevant hardware, compile options. Notes: How this file differs from the general case.
Function1: Kernel version it was based on. What it is (briefly). Describe it's operation relative to other functions of the same type (i.e. how is it different from the general case.) Bugs/limitations Notes
Function2: (likewise)
I mention the general case. I think there should be a file that describes each standard interface. For example, the standard functions used by a character special device.
In each major directory there should also probably be a "glossary", i.e. in the "net" directory it might include a definition of and explanation of "skbuff".
I would be willing to maintain the files, although I don't have enough knowledge yet to actually write most if any of them.
If this is to be done there needs to be a seperate list for it, or at least an understanding not to discuss it (much if any) here.
--kmb203@psu.edu----------------Debian/GNU--1.3---Linux--2.0.30--- To A Quick Young Fox: Why jog exquisite bulk, fond crazy vamp, Daft buxom jonquil, zephyr's gawky vice? Guy fed by work, quiz Jove's xanthic lamp -- Zow! Qualms by deja vu gyp fox-kin thrice. -- Lazy Dog
| |