Update^5: Fix PR other/44034

[Joern Rennecke]

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)