Re: Update^5: Fix PR other/44034

[Joern Rennecke <amylaar at spamcop dot net>]

Quoting "Joseph S. Myers" <joseph@codesourcery.com>:

> The comments at the start of target.def should explain the macro
> DEFHOOK_UNDOC.  They should also make clear which cases are obsolescent
> and should not be used for new hooks but are used for existing hooks
> pending appropriate license approvals from the FSF and the writing of
> documentation for hooks currently lacking it (as I understand it, all
> cases involving _UNDOC, "*" or "" for documentation or the presence of a
> comment above a DEFHOOK* macro call).

Like this?

/* A hook should generally be documented by a string in the DOC parameter,
   which should contain texinfo markup.  If the documentation is only  
available
   under the GPL, but not under the GFDL, put it in a comment above the hook
   definition.  If the function declaration is available both under GPL and
   GFDL, but the documentation is only available under the GFDL, put the
   documentaton in tm.texi.in, heading with @hookdoc <hookname> and closing
   the paragraph with @end deftypefn / deftypevr as appropriate, and marking
   the next autogenerated hook with @hookdoc <hookname>.
   In both these cases, leave the DOC string empty, i.e. "".
   Sometimes, the function declaration itself is only available under the
   GPL, and/or for some historic reason it has to be documented differently
   than what it is.  In that case, use DEFHOOK_UNDOC to supress  
auto-generation
   of documentation.  DEFHOOK_UNDOC takes a DOC string which it ignores, so
   you can put GPLed documentation string there if you have hopes that you
   can clear the declaration & documentation for GFDL distribution later,
   in which case you can then simply change the DEFHOOK_UNDOC to DEFHOOK
   to turn on the autogeneration of the documentation.

   A documentation string of "*" means not to emit any documentation at all,
   and is mainly used internally for DEFHOOK_UNDOC.  It should generally not
   be used otherwise, but it has its use for exceptional cases where automatic
   documentation is not wanted, and the real documentation is elsewere, like
   for TARGET_ASM_{,UN}ALIGNED_INT_OP, which are hooks only for implementation
   purposes; they refer to structs, the components of which are documented as
   separate hooks TARGET_ASM_{,UN}ALIGNED_[HSDT]I_OP.
   A DOC string of 0 is for internal use of DEFHOOKPODX and special table
   entries only.  */

> New generator files such as genhooks.c should be listed in po/EXCLUDES so
> they don't get messages extracted from them for translation.
>
> genhooks.c has an unchecked fopen call; just because a previous call to
> fopen for the same file succeeded doesn't mean a new one will.

Is am currently putting a patch to r160960 with fixes to the issues you
raised through a regression test; it also has a DEFHOOK_UNDOC for the new
declare_constant_name, which unfortunately differs in argument naming in
varasm.c / config/darwin.c from tm.texi. (exp is GPLed vs. expr is GFDLed)