[lkml]   [1999]   [Sep]   [25]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
    SubjectRe: [Q]: Linux and real device drivers
    David Hinds writes:
    > On Sat, Sep 25, 1999 at 05:58:37PM +0100, Alan Cox wrote:
    > > > Relying on the kernel source code as a primary means of communication
    > > > between key kernel developers is simply wrong.
    > >
    > > Any better ideas. None I have seen in any other free project worked.
    > One suggestion would be to have a set of man pages included in the
    > kernel tree. And try to make them sufficiently useful that people
    > would want to keep them up to date. In this case, I think adding to
    > the kernel tree would be a good thing, because it keeps the
    > documentation in the same place as what it is documenting. I'd be
    > willing to write man pages for a few things myself. The current
    > documentation in the kernel tree is a bit too informal and
    > incomplete.

    Yes. I advocate embedding markup tags in a comment block for each
    function, which can then be automatically extracted to generate man
    pages. This keeps the API documentation right there in the source
    code, which vastly increases the chances that an update will be
    reflected in the documentation.

    If you look at my devfs patch, you can see what it looks like
    (fs/devfs/base.c). Also look at smp_call_function() in
    arch/i386/kernel/smp.c for an example.

    I've got code which extracts this and allows you to generate man pages
    and HTML (complete with cross-referencing/hyperlinks). I've been using
    this scheme for years now. It works really well.

    It's a lot of work to go through code and add all those markups, but
    it's worth the effort in the long run. Once you're set up and in a
    routine, you never have to worry about API documentation again.



    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to
    Please read the FAQ at

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