Documentation for target macros: comments vs. tm.texi

[Joseph S. Myers]

Target macros are supposed to be documented in tm.texi, although there are
many that are not (e.g. all those for the current varargs/stdarg
implementation via built-in functions).  In addition, many target header
files contain lengthy comments above the definitions of the target macros,
which just describe the macro but nothing specific to that target's
definition of it.

I think this duplication of documentation is a bad idea; we should try to
have good documentation of each target macro in one place, tm.texi, and
should only have comments on the definitions of these macros if they say
something useful about that target's definition.  (Of course, when
removing the comments they should be checked to see if they say anything
useful that should go in the manual proper.)  projects/beginner.html
already notes that commented-out definitions of macros should be removed
from the target headers, so that grep is more useful, and it has been
discussed that in many cases the same definition is used on most targets,
and should go in defaults.h and be removed from the targets that use the
default.

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?

-- 
Joseph S. Myers
jsm28@cam.ac.uk