This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: law at redhat dot com
- To: Ian Lance Taylor <ian at wasabisystems dot com>
- Cc: kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner), Joe dot Buck at synopsys dot com, gcc at gcc dot gnu dot org
- Date: Thu, 29 Jan 2004 11:32:41 -0700
- Subject: Re: "Documentation by paper"
- Reply-to: law at redhat dot com
In message <m34quhjii1.fsf@gossamer.airs.com>, Ian Lance Taylor writes:
>law@redhat.com writes:
>
>> IMHO that's actually a huge long term liability as it actually discourages
>> writing good API interfaces and documenting them, while at the same time
>> encourages developers to actually look at the implementation to determine
>> if the code in question actually does what they want.
>
>I agree with you, but extracting documentation automatically from
>source code comments, and from the source code itself, isn't API
>documentation either. It's just another way of reading the source
>code.
Agreed. My point was that the way we do things now discourages us from
actually having well-defined APIs and encourages developers to dig into
the implementation details.
Conceptually, an API should be usable without looking at the implementation.
Jeff