[PATCH 7/8] Use @deftypefn in chew output

[Simon Marchi]

On 2/8/23 02:17, Tom Tromey wrote:
> 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.
> 
> bfd/ChangeLog
> 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.

Hi Tom,

Starting with this commit, I see this when building (with ASan enabled):

  GEN      doc/aoutx.stamp

=================================================================
==45648==ERROR: LeakSanitizer: detected memory leaks

Direct leak of 14 byte(s) in 1 object(s) allocated from:
    #0 0x7f193eebfa89 in __interceptor_malloc /usr/src/debug/gcc/gcc/libsanitizer/asan/asan_malloc_linux.cpp:69
    #1 0x55a292052ba0 in xmalloc /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:158
    #2 0x55a29205678a in nextword /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:1090
    #3 0x55a292057c1e in compile /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:1331
    #4 0x55a292058b8b in main /home/smarchi/src/binutils-gdb/bfd/doc/chew.c:1511
    #5 0x7f193ec3c78f  (/usr/lib/libc.so.6+0x2378f)

Simon