[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: continuing documentation

From: Jim Franklin
Subject: RE: continuing documentation
Date: Wed, 20 Jun 2001 08:41:32 -0700

Hi folks,
 Rather than changing headers in the source code for clarification perhaps
something could be done using an external cross referencing tools to make
notes that expand on the header info. If everyone were to agree to use one
particular tool for x-ref then the notes could be shared between all
developers and a repository for notes could be kept somewhere at gnu.org .


-----Original Message-----
From: bug-hurd-admin@gnu.org [mailto:bug-hurd-admin@gnu.org]On Behalf Of
Gordon Matzigkeit
Sent: Friday, June 29, 2001 3:05 PM
To: Thomas Bushnell, BSG
Cc: OKUJI Yoshinori; bill.white@griggsinst.com; baux@debian.org;
Subject: Re: continuing documentation

>>>>> Thomas Bushnell, BSG writes:

 TBB> OKUJI Yoshinori <okuji@kuicr.kyoto-u.ac.jp> writes:
 >> For now, I'm afraid of two things about that. One of these is that
 >> people often write documents and comments differently, of course,
 >> intentionally.

 TBB> I agree with Okuji here.  The job of the comment in a header
 TBB> file is to remind a programmer what the interface is.  The job
 TBB> of the manual is to explain the interface.

Okay, I can agree with that.  The constraint I was operating under was
to give some way of indicating to a documentor when an interface
change has been made, and indicating to the coder when a description
has been clarified.

Perhaps just `diffmon' is good enough, and is already as specific as

 Gordon Matzigkeit <gord@fig.org>  //\ I'm a FIG (http://fig.org/)
Committed to freedom and diversity \// I use GNU (http://fig.org/gnu/)

Bug-hurd mailing list

reply via email to

[Prev in Thread] Current Thread [Next in Thread]