This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Mark Mitchell <mark at codesourcery dot com>
- To: Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Cc: gcc at gcc dot gnu dot org
- Date: Fri, 30 Jan 2004 15:15:40 -0800
- Subject: Re: "Documentation by paper"
- Organization: CodeSourcery, LLC
- References: <10401271524.AA28491@vlsi1.ultra.nyu.edu>
Richard Kenner wrote:
I've been noticing for a while that there are an increasing number of files
in GCC where the only overview documentation is a reference to a paper or
textbook.
I think this is totally unacceptable documentation and that we need to have a
policy about this sort of documentation.
Very little discussion in the long ensuing thread seems to relate back
to this key point from Kenner's original email. Independent of the pros
and cons of Doxygen and its ilk, let's agree that documentation has to
be present in the GCC source tree for the algorithms that are in use in
the compiler. If you write new code, it's good to reference papers that
inspired it, but that's no excuse for good comments on the functions
that explain what they do and good comments in the code that explain why
it works the way it does.
I don't think we need to officially adopt Kenner's list of policies
because I think they are already implied by our current coding standards.
But, we do need to enforce them!
--
Mark Mitchell
CodeSourcery, LLC
(916) 791-8304
mark@codesourcery.com