From b8e81f19cbbe978c7376795129ee90ee8e73cf0a Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Tue, 7 Feb 2023 21:40:53 -0700 Subject: 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 * 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. --- bfd/syms.c | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'bfd/syms.c') diff --git a/bfd/syms.c b/bfd/syms.c index a26aeb4..c460e37 100644 --- a/bfd/syms.c +++ b/bfd/syms.c @@ -642,12 +642,12 @@ decode_section_type (const struct bfd_section *section) FUNCTION bfd_decode_symclass +SYNOPSIS + int bfd_decode_symclass (asymbol *symbol); + DESCRIPTION Return a character corresponding to the symbol class of @var{symbol}, or '?' for an unknown class. - -SYNOPSIS - int bfd_decode_symclass (asymbol *symbol); */ int bfd_decode_symclass (asymbol *symbol) @@ -725,13 +725,13 @@ bfd_decode_symclass (asymbol *symbol) FUNCTION bfd_is_undefined_symclass +SYNOPSIS + bool bfd_is_undefined_symclass (int symclass); + DESCRIPTION Returns non-zero if the class symbol returned by bfd_decode_symclass represents an undefined symbol. Returns zero otherwise. - -SYNOPSIS - bool bfd_is_undefined_symclass (int symclass); */ bool @@ -744,13 +744,13 @@ bfd_is_undefined_symclass (int symclass) FUNCTION bfd_symbol_info +SYNOPSIS + void bfd_symbol_info (asymbol *symbol, symbol_info *ret); + DESCRIPTION Fill in the basic info about symbol that nm needs. Additional info may be added by the back-ends after calling this function. - -SYNOPSIS - void bfd_symbol_info (asymbol *symbol, symbol_info *ret); */ void -- cgit v1.1