bfd/doc/chew.c extracts documentation from source code comments
annotated with keywords, and generates much of bfd.h and libbfd.h from
those same comments. The docs have suffered from people (me too)
adding things like CODE_FRAGMENT to the source to put code into bfd.h
without realising that CODE_FRAGMENT also puts @example around said
code into the docs. So we have random senseless things in the docs.
This patch fixes that problem (well, the senseless things from
CODE_FRAGMENT), moves most of the code out of bfd-in.h, and improves a
few chew.c features. libbfd.h now automatically gets ATTRIBUTE_HIDDEN
prototypes, and indentation in bfd.h and libbfd.h is better.
Currently, if a function description spans a line, the resulting info
can look like this:
-- Function: long bfd_canonicalize_reloc
(bfd *abfd, asection *sec, arelent **loc, asymbol **syms); Call the
back end associated with the open BFD ABFD and translate the
external form of the relocation information attached to SEC into
the internal canonical form. Place the table into memory at LOC,
That is, the function prototype runs together with the text in an ugly
way. This patch fixes this by introducing a new primitive, so that
the generated Texinfo can be a bit nicer. Now this output looks like:
-- Function: long bfd_canonicalize_reloc (bfd *abfd, asection *sec,
arelent **loc, asymbol **syms);
Call the back end associated with the open BFD ABFD and translate
the external form of the relocation information attached to SEC
2023-02-17 Tom Tromey <tom@tromey.com>
* doc/doc.str (SYNOPSIS): Use collapse_whitespace.
* doc/chew.c (collapse_whitespace): New function.
(main): Register collapse_whitespace.
When reading the BFD manual, I noticed text like this:
-- Function: bool bfd_close (bfd *abfd);
Close a BFD. If the BFD was open for writing, then pending
operations are completed and the file written out and closed. If
...
*Returns*
'TRUE' is returned if all is ok, otherwise 'FALSE'.
The *Returns*, like the *Synopsis* in the earlier patch, is
un-info-like. It's also used inconsistently.
This patch removes all the uses of the RETURNS word and removes it
entirely from the chew scripts. Now this example reads:
-- Function: bool bfd_close (bfd *abfd);
Close a BFD. If the BFD was open for writing, then pending
operations are completed and the file written out and closed. If
...
'TRUE' is returned if all is ok, otherwise 'FALSE'.
In a few cases I had to slightly reword the comment. There were also
a couple of cases where there was redundant text. In these cases I
just dropped the RETURNS copy.
2023-02-07 Tom Tromey <tom@tromey.com>
* bfd.c, cache.c, compress.c, opncls.c: Remove RETURNS from
documentation comments.
* doc/doc.str, doc/proto.str (RETURNS): Remove.
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.
The .str script files don't have copyright headers, but I think they
should. I used the same dates that chew.c uses, which I think makes
sense because these are inputs to chew.
2023-02-07 Tom Tromey <tom@tromey.com>
* doc/doc.str, doc/proto.str: Add copyright header.
