This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: Documentation for target macros: comments vs. tm.texi
- From: "Joseph S. Myers" <jsm28 at cam dot ac dot uk>
- To: Stan Shebs <shebs at apple dot com>
- Cc: <gcc at gcc dot gnu dot org>, <gcc-patches at gcc dot gnu dot org>
- Date: Mon, 7 Jan 2002 23:23:51 +0000 (GMT)
- Subject: Re: Documentation for target macros: comments vs. tm.texi
On Mon, 7 Jan 2002, Stan Shebs wrote:
> "Joseph S. Myers" wrote:
> >
> > Any comments on the idea of getting rid of the generic comments from the
> > definitions of the target macros, leaving only useful comments about the
> > definition on a particular system?
>
> Absolutely yes. If any of cookie-cutter comments are still accurate,
> it's by sheer inertia. There was a theory at one point that machine
> descriptions would be created from templates, and the comments were
> supposed to guide the porter in whether to uncomment a definition
> and/or alter it. But in the absence of any sort of automatic
> update mechanism, it was just a matter of months before the template
> derived descriptions included out-of-date info.
I've applied the following patch to add removing these comments as a
project to beginner.html
Index: beginner.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/projects/beginner.html,v
retrieving revision 1.14
diff -u -r1.14 beginner.html
--- beginner.html 2001/12/17 19:53:18 1.14
+++ beginner.html 2002/01/07 23:21:40
@@ -452,6 +452,24 @@
will get no false positives.</p>
</li>
+<li>Remove comments above macro definitions in the <code>tm.h</code>
+files that only describe the meaning of the macro and say nothing specific
+to that machine.
+
+<p>These comments have largely been copied from one <code>tm.h</code>
+file to another, and many may be out of date by now. Target macros
+should be documented in <code>tm.texi</code> only, not in the
+individual target headers. However, where there are comments
+describing the reason for a particular target's choice of definition,
+or saying something about that choice beyond repeating what the
+definition means, those comments should be preserved.</p>
+
+<p>When removing comments describing target macros (whether on
+definitions of those macros, or on commented-out definitions), make
+sure that the macro is documented in <code>tm.texi</code> and the
+comments don't say anything more that ought to be in the manual.</p>
+</li>
+
<li>Convert huge macros in each <code>tm.h</code> to functions in the
corresponding <code>tm.c</code>.
--
Joseph S. Myers
jsm28@cam.ac.uk