* [PATCH 1/4] Fix formatting of long function description in chew output
2023-02-17 19:29 [PATCH 0/4] More fixes to chew documentation Tom Tromey
@ 2023-02-17 19:29 ` Tom Tromey
2023-02-17 19:29 ` [PATCH 2/4] Don't use chew comments for static functions Tom Tromey
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Tom Tromey @ 2023-02-17 19:29 UTC (permalink / raw)
To: binutils; +Cc: Tom Tromey
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
bfd/ChangeLog
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.
---
bfd/ChangeLog | 6 ++++++
bfd/doc/chew.c | 33 +++++++++++++++++++++++++++++++++
bfd/doc/doc.str | 2 ++
3 files changed, 41 insertions(+)
diff --git a/bfd/doc/chew.c b/bfd/doc/chew.c
index 19e3781bdda..eca9305fee0 100644
--- a/bfd/doc/chew.c
+++ b/bfd/doc/chew.c
@@ -884,6 +884,38 @@ kill_bogus_lines (void)
}
+static void
+collapse_whitespace (void)
+{
+ int last_was_ws = 0;
+ int idx;
+
+ string_type out;
+ init_string (&out);
+
+ for (idx = 0; at (tos, idx) != 0; ++idx)
+ {
+ char c = at (tos, idx);
+ if (isspace (c))
+ {
+ if (!last_was_ws)
+ {
+ catchar (&out, ' ');
+ last_was_ws = 1;
+ }
+ }
+ else
+ {
+ catchar (&out, c);
+ last_was_ws = 0;
+ }
+ }
+
+ pc++;
+ delete_string (tos);
+ *tos = out;
+}
+
static void
indent (void)
{
@@ -1479,6 +1511,7 @@ main (int ac, char *av[])
add_intrinsic ("indent", indent);
add_intrinsic ("print_stack_level", print_stack_level);
add_intrinsic ("strip_trailing_newlines", strip_trailing_newlines);
+ add_intrinsic ("collapse_whitespace", collapse_whitespace);
internal_mode = xmalloc (sizeof (intptr_t));
*internal_mode = 0;
diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index 2a0953a3ece..5077ada9812 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -55,8 +55,10 @@ variable synopsis_seen
"@deftypefn {Function} " catstr
get_stuff_in_command
kill_bogus_lines
+ collapse_whitespace
indent
catstr
+ "\n" catstr
;
: func
--
2.39.1
^ permalink raw reply [flat|nested] 6+ messages in thread* [PATCH 2/4] Don't use chew comments for static functions
2023-02-17 19:29 [PATCH 0/4] More fixes to chew documentation Tom Tromey
2023-02-17 19:29 ` [PATCH 1/4] Fix formatting of long function description in chew output Tom Tromey
@ 2023-02-17 19:29 ` Tom Tromey
2023-02-17 19:29 ` [PATCH 3/4] Hoist the SECTION comment in opncls.c Tom Tromey
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Tom Tromey @ 2023-02-17 19:29 UTC (permalink / raw)
To: binutils; +Cc: Tom Tromey
I found a few static functions in the BFD manual. These can't be
called by any user of the library, so I don't think it's useful to put
them in the manual. This patch removes the chew markup from their
comments.
bfd/ChangeLog
2023-02-17 Tom Tromey <tom@tromey.com>
* opncls.c (bfd_get_debug_link_info_1, separate_debug_file_exists)
(separate_alt_debug_file_exists, find_separate_debug_file)
(get_build_id, get_build_id_name, check_build_id_file): Don't use
chew comments.
---
bfd/ChangeLog | 7 +++
bfd/opncls.c | 170 +++++++++++++++-----------------------------------
2 files changed, 58 insertions(+), 119 deletions(-)
diff --git a/bfd/opncls.c b/bfd/opncls.c
index eeac5825dbf..95906526973 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -1165,29 +1165,20 @@ bfd_calc_gnu_debuglink_crc32 (unsigned long crc,
}
-/*
-INTERNAL_FUNCTION
- bfd_get_debug_link_info_1
-
-SYNOPSIS
- char *bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out);
-
-DESCRIPTION
- Extracts the filename and CRC32 value for any separate debug
- information file associated with @var{abfd}.
+/* Extracts the filename and CRC32 value for any separate debug
+ information file associated with @var{abfd}.
- The @var{crc32_out} parameter is an untyped pointer because
- this routine is used as a @code{get_func_type} function, but it
- is expected to be an unsigned long pointer.
+ The @var{crc32_out} parameter is an untyped pointer because
+ this routine is used as a @code{get_func_type} function, but it
+ is expected to be an unsigned long pointer.
- Returns the filename of the associated debug information file,
- or NULL if there is no such file. If the filename was found
- then the contents of @var{crc32_out} are updated to hold the
- corresponding CRC32 value for the file.
+ Returns the filename of the associated debug information file,
+ or NULL if there is no such file. If the filename was found
+ then the contents of @var{crc32_out} are updated to hold the
+ corresponding CRC32 value for the file.
- The returned filename is allocated with @code{malloc}; freeing
- it is the responsibility of the caller.
-*/
+ The returned filename is allocated with @code{malloc}; freeing
+ it is the responsibility of the caller. */
static char *
bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out)
@@ -1322,22 +1313,12 @@ bfd_get_alt_debug_link_info (bfd * abfd, bfd_size_type *buildid_len,
return name;
}
-/*
-INTERNAL_FUNCTION
- separate_debug_file_exists
-
-SYNOPSIS
- bool separate_debug_file_exists
- (char *name, void *crc32_p);
-
-DESCRIPTION
- Checks to see if @var{name} is a file and if its contents
- match @var{crc32}, which is a pointer to an @code{unsigned
- long} containing a CRC32.
+/* Checks to see if @var{name} is a file and if its contents match
+ @var{crc32}, which is a pointer to an @code{unsigned long}
+ containing a CRC32.
- The @var{crc32_p} parameter is an untyped pointer because
- this routine is used as a @code{check_func_type} function.
-*/
+ The @var{crc32_p} parameter is an untyped pointer because this
+ routine is used as a @code{check_func_type} function. */
static bool
separate_debug_file_exists (const char *name, void *crc32_p)
@@ -1365,17 +1346,7 @@ separate_debug_file_exists (const char *name, void *crc32_p)
return crc == file_crc;
}
-/*
-INTERNAL_FUNCTION
- separate_alt_debug_file_exists
-
-SYNOPSIS
- bool separate_alt_debug_file_exists
- (char *name, void *unused);
-
-DESCRIPTION
- Checks to see if @var{name} is a file.
-*/
+/* Checks to see if @var{name} is a file. */
static bool
separate_alt_debug_file_exists (const char *name, void *unused ATTRIBUTE_UNUSED)
@@ -1393,33 +1364,22 @@ separate_alt_debug_file_exists (const char *name, void *unused ATTRIBUTE_UNUSED)
return true;
}
-/*
-INTERNAL_FUNCTION
- find_separate_debug_file
+/* Searches for a debug information file corresponding to @var{abfd}.
-SYNOPSIS
- char *find_separate_debug_file
- (bfd *abfd, const char *dir, bool include_dirs,
- get_func_type get, check_func_type check, void *data);
+ The name of the separate debug info file is returned by the
+ @var{get} function. This function scans various fixed locations
+ in the filesystem, including the file tree rooted at @var{dir}.
+ If the @var{include_dirs} parameter is true then the directory
+ components of @var{abfd}'s filename will be included in the
+ searched locations.
-DESCRIPTION
- Searches for a debug information file corresponding to @var{abfd}.
-
- The name of the separate debug info file is returned by the
- @var{get} function. This function scans various fixed locations
- in the filesystem, including the file tree rooted at @var{dir}.
- If the @var{include_dirs} parameter is true then the directory
- components of @var{abfd}'s filename will be included in the
- searched locations.
-
- @var{data} is passed unmodified to the @var{get} and @var{check}
- functions. It is generally used to implement build-id-like
- matching in the callback functions.
-
- Returns the filename of the first file to be found which
- receives a TRUE result from the @var{check} function.
- Returns NULL if no valid file could be found.
-*/
+ @var{data} is passed unmodified to the @var{get} and @var{check}
+ functions. It is generally used to implement build-id-like
+ matching in the callback functions.
+
+ Returns the filename of the first file to be found which
+ receives a TRUE result from the @var{check} function.
+ Returns NULL if no valid file could be found. */
typedef char * (*get_func_type) (bfd *, void *);
typedef bool (*check_func_type) (const char *, void *);
@@ -1818,23 +1778,14 @@ bfd_fill_in_gnu_debuglink_section (bfd *abfd,
return true;
}
-/*
-INTERNAL_FUNCTION
- get_build_id
-
-SYNOPSIS
- struct bfd_build_id * get_build_id (bfd *abfd);
+/* Finds the build-id associated with @var{abfd}. If the build-id is
+ extracted from the note section then a build-id structure is built
+ for it, using memory allocated to @var{abfd}, and this is then
+ attached to the @var{abfd}.
-DESCRIPTION
- Finds the build-id associated with @var{abfd}. If the build-id is
- extracted from the note section then a build-id structure is built
- for it, using memory allocated to @var{abfd}, and this is then
- attached to the @var{abfd}.
-
- Returns a pointer to the build-id structure if a build-id could be
- found. If no build-id is found NULL is returned and error code is
- set.
-*/
+ Returns a pointer to the build-id structure if a build-id could be
+ found. If no build-id is found NULL is returned and error code is
+ set. */
static struct bfd_build_id *
get_build_id (bfd *abfd)
@@ -1919,25 +1870,15 @@ get_build_id (bfd *abfd)
return build_id;
}
-/*
-INTERNAL_FUNCTION
- get_build_id_name
-
-SYNOPSIS
- char * get_build_id_name (bfd *abfd, void *build_id_out_p)
+/* Searches @var{abfd} for a build-id, and then constructs a pathname
+ from it. The path is computed as .build-id/NN/NN+NN.debug where
+ NNNN+NN is the build-id value as a hexadecimal string.
-DESCRIPTION
- Searches @var{abfd} for a build-id, and then constructs a pathname
- from it. The path is computed as .build-id/NN/NN+NN.debug where
- NNNN+NN is the build-id value as a hexadecimal string.
-
- Returns the constructed filename or NULL upon error.
- It is the caller's responsibility to free the memory used to hold the
- filename.
- If a filename is returned then the @var{build_id_out_p}
- parameter (which points to a @code{struct bfd_build_id}
- pointer) is set to a pointer to the build_id structure.
-*/
+ Returns the constructed filename or NULL upon error. It is the
+ caller's responsibility to free the memory used to hold the
+ filename. If a filename is returned then the @var{build_id_out_p}
+ parameter (which points to a @code{struct bfd_build_id} pointer) is
+ set to a pointer to the build_id structure. */
static char *
get_build_id_name (bfd *abfd, void *build_id_out_p)
@@ -1981,21 +1922,12 @@ get_build_id_name (bfd *abfd, void *build_id_out_p)
return name;
}
-/*
-INTERNAL_FUNCTION
- check_build_id_file
+/* Checks to see if @var{name} is a readable file and if its build-id
+ matches @var{buildid}.
-SYNOPSIS
- bool check_build_id_file (char *name, void *buildid_p);
-
-DESCRIPTION
- Checks to see if @var{name} is a readable file and if its build-id
- matches @var{buildid}.
-
- Returns TRUE if the file exists, is readable, and contains a
- build-id which matches the build-id pointed at by
- @var{build_id_p} (which is really a @code{struct bfd_build_id **}).
-*/
+ Returns TRUE if the file exists, is readable, and contains a
+ build-id which matches the build-id pointed at by @var{build_id_p}
+ (which is really a @code{struct bfd_build_id **}). */
static bool
check_build_id_file (const char *name, void *buildid_p)
--
2.39.1
^ permalink raw reply [flat|nested] 6+ messages in thread