[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 .
Jim
-----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;
bug-hurd@gnu.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
possible.
--
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
Bug-hurd@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-hurd
- Re: continuing documentation, (continued)
- Re: continuing documentation, Gordon Matzigkeit, 2001/06/21
- Re: continuing documentation, Roland McGrath, 2001/06/21
- Re: continuing documentation, OKUJI Yoshinori, 2001/06/21
- Re: continuing documentation, Gordon Matzigkeit, 2001/06/22
- Re: continuing documentation, OKUJI Yoshinori, 2001/06/23
- Re: continuing documentation, Gordon Matzigkeit, 2001/06/23
- Re: continuing documentation, Maurizio Boriani, 2001/06/26
- Re: continuing documentation, Gordon Matzigkeit, 2001/06/28
- Re: continuing documentation, Thomas Bushnell, BSG, 2001/06/29
- Re: continuing documentation, Gordon Matzigkeit, 2001/06/29
- RE: continuing documentation,
Jim Franklin <=
- Re: continuing documentation, Bill White, 2001/06/21
RE: continuing documentation, Chen Shapira, 2001/06/21