This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Lars Segerlund <lars dot segerlund at comsys dot se>
- To: gcc at gcc dot gnu dot org
- Date: Mon, 2 Feb 2004 12:01:56 +0100
- Subject: Re: "Documentation by paper"
- References: <10401271524.AA28491@vlsi1.ultra.nyu.edu><401AE59C.9080809@codesourcery.com>
I think a nice point to make would be that nothing that's not documented gets 'in'.
Particularily algorithms and such, this way people could discuss an issue instead for waitning for the trouble to show up.
/ Lars Segerlund.
On Fri, 30 Jan 2004 15:15:40 -0800
Mark Mitchell <mark@codesourcery.com> wrote:
> 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
>