lkml.org 
[lkml]   [1997]   [Jul]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    SubjectRe: Take A deep Breath - Kernel Documentation
    Date
    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!

    \
     
     \ /
      Last update: 2005-03-22 13:39    [W:0.022 / U:149.480 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site