Re: Take A deep Breath - Kernel Documentation
david parsons (o.r.c@p.e.l.l.p.o.r.t.l.a.n.d.o.r.u.s)
21 Jul 1997 13:52:18 -0700
In article <linux.kernel.m0wq3ci-00002hC@brando>,
Kevin M. Bealer <kmb203@psu.edu> wrote:
>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.
Both of these reasons are arguments for keeping the documentation
IN the code; If it's a separate file, the designer may forget that
it's even there (particularly on a group development effort like
Linux) and thus not update the code (the whole idea of having one
person write the code and another person document it is, well, an
unexpected refugee from the IBM mainframe world in the 1970s.)
>3. Obvious kernel tarball size arguments. (Imagine the traffic..)
The source is 8mb (compressed) already, and this includes
documentation.
____
david parsons \bi/ code and primary documentation in separate files?
\/ Out, Out!