This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]