Use @deftypefn in chew output

When reading the BFD info manual, function definitions looked very
strange to me:

    *Synopsis*
	 long bfd_get_mtime (bfd *abfd);
       *Description*
    Return the file modification time (as read from the file system, or from
    the archive header for archive members).

The *Synopsis* and *Description* text in particular is very un-info-like.

To fix this, I tried removing the *Synopsis* text and having FUNCTION
use @deftypefn instead.  However, this ended up requiring some new
state, because SYNOPSIS can appear without FUNCTION.  This in turn
required "catstrif" (I considered adding FORTH-style if-else-then, but
in the end decided on an ad hoc approach).

After this the result looks like:

 -- Function: long bfd_get_mtime (bfd *abfd);
     Return the file modification time (as read from the file system, or
     from the archive header for archive members).

This patch also reorders a few documentation comments to ensure that
SYNOPSIS comes before DESCRIPTION.  This is the more common style and
is also now required by doc.str.

2023-02-07  Tom Tromey  <tom@tromey.com>

	* syms.c (bfd_decode_symclass, bfd_is_undefined_symclass)
	(bfd_symbol_info): Reorder documentation comment.
	* doc/doc.str (synopsis_seen): New variable.
	(SYNOPSIS): Set synopsis_seen.  Emit @deftypefn.
	(DESCRIPTION): Use synopsis_seen.
	* doc/chew.c (catstrif): New function.
	(main): Add catstrif intrinsic.
	(compile): Recognize "variable" command.

0 files changed, 0 insertions, 0 deletions