FIXME: For pre-existing hooks, we can't place the documentation in the
documentation field here till we get permission from the FSF to include
it in GPLed software - the target hook documentation is so far only
available under the GFDL.
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 @hook <hookname> and closing
the paragraph with @end deftypefn / deftypevr as appropriate, and marking
the next autogenerated hook with @hook <hookname>.
In both these cases, leave the DOC string empty, i.e. "".
Sometimes, for some historic reason the function declaration
has to be documented differently
than what it is. In that case, use DEFHOOK_UNDOC to suppress 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. Empty macro arguments are undefined in C90, so use an empty macro
to close top-level hook structures.
1.12.0