[applied] abipkgdiff.rst: Sort options documentation items alphabetically

Message ID 87cyfzjc51.fsf@redhat.com
State New
Headers
Series [applied] abipkgdiff.rst: Sort options documentation items alphabetically |

Commit Message

Dodji Seketeli Feb. 3, 2025, 3:12 p.m. UTC
  Hello,

This patch sorts the description of the options of the abipkgdiff tool
alphabetically.

	* abipkgdiff.rst: Sort the options alphabetically.

Signed-off-by: Dodji Seketeli <dodji@redhat.com>
Applied to the mainline.
---
 doc/manuals/abipkgdiff.rst | 507 ++++++++++++++++++++-----------------
 1 file changed, 273 insertions(+), 234 deletions(-)
  

Patch

diff --git a/doc/manuals/abipkgdiff.rst b/doc/manuals/abipkgdiff.rst
index cba6fddb..561e4342 100644
--- a/doc/manuals/abipkgdiff.rst
+++ b/doc/manuals/abipkgdiff.rst
@@ -80,13 +80,43 @@  documented further below) to provide a suppression specification.
 Options
 =======
 
-  * ``--help | -h``
+  * ``--allow-non-exported-interfaces``
 
-    Display a short help about the command and exit.
+    When looking at the debug information accompanying a binary, this
+    tool analyzes the descriptions of the types reachable by the
+    interfaces (functions and variables) that are visible outside of
+    their translation unit.  Once that analysis is done, an ABI corpus
+    is constructed by only considering the subset of types reachable
+    from interfaces associated to `ELF`_ symbols that are defined and
+    exported by the binary.  It's those final ABI Corpora that are
+    compared by this tool.
 
-  * `--version | -v`
+    The problem with that approach however is that analyzing all the
+    interfaces that are visible from outside their translation unit
+    can amount to a lot of data, especially when those binaries are
+    applications, as opposed to shared libraries.  One example of such
+    applications is the `Linux Kernel`_.  Analyzing massive ABI
+    Corpora like these can be extremely slow.
+
+    In the presence of an "average sized" binary however one can
+    afford having libabigail analyze all interfaces that are visible
+    outside of their translation unit, using this option.
+
+    Note that this option is turned on by default, unless we are in
+    the presence of the `Linux Kernel`_.
+
+
+  * ``--btf``
+
+     This is used to compare packages with `BTF`_ debug information,
+     if present.
+
+
+  * ``--ctf``
+
+     This is used to compare packages with `CTF`_ debug information,
+     if present.
 
-    Display the version of the program and exit.
 
   * ``--debug-info-pkg1 | --d1`` <path>
 
@@ -99,6 +129,7 @@  Options
     instances of this options can be provided, along with those
     several different debug info packages.
 
+
   * ``--debug-info-pkg2 | --d2`` <path>
 
     For cases where the debug information for *package2* is split out
@@ -110,6 +141,7 @@  Options
     instances of this options can be provided, along with those
     several different debug info packages.
 
+
   * ``--devel-pkg1 | --devel1`` <path>
 
     Specifies where to find the `Development Package`_ associated with
@@ -120,6 +152,7 @@  Options
     filters out reports about ABI changes to types that are *NOT*
     defined in these header files.
 
+
   * ``--devel-pkg2 | --devel2`` <path>
 
     Specifies where to find the `Development Package`_ associated with
@@ -130,6 +163,7 @@  Options
     filters out reports about ABI changes to types that are *NOT*
     defined in these header files.
 
+
   * ``--drop-private-types``
 
     This option is to be used with the ``--devel-pkg1`` and
@@ -148,24 +182,106 @@  Options
     consumption of the tool on binaries with a lot of publicly defined
     and exported types.
 
+
   * ``--dso-only``
 
     Compare ELF files that are shared libraries, only.  Do not compare
     executable files, for instance.
 
-  * ``--private-dso``
 
-    By default, ``abipkgdiff`` does not compare DSOs that are private
-    to the RPM package.  A private DSO is a DSO which SONAME is *NOT*
-    advertised in the "provides" property of the RPM.
+  * ``--exported-interfaces-only``
 
-    This option instructs ``abipkgdiff`` to *also* compare DSOs that
-    are *NOT* advertised in the "provides" property of the RPM.
+    By default, when looking at the debug information accompanying a
+    binary, this tool analyzes the descriptions of the types reachable
+    by the interfaces (functions and variables) that are visible
+    outside of their translation unit.  Once that analysis is done, an
+    ABI corpus is constructed by only considering the subset of types
+    reachable from interfaces associated to `ELF`_ symbols that are
+    defined and exported by the binary.  It's those final ABI Corpora
+    that are compared by this tool.
+
+    The problem with that approach however is that analyzing all the
+    interfaces that are visible from outside their translation unit
+    can amount to a lot of data, especially when those binaries are
+    applications, as opposed to shared libraries.  One example of such
+    applications is the `Linux Kernel`_.  Analyzing massive ABI
+    corpora like these can be extremely slow.
+
+    To mitigate that performance issue, this option allows libabigail
+    to only analyze types that are reachable from interfaces
+    associated with defined and exported `ELF`_ symbols.
+
+    Note that this option is turned on by default when analyzing the
+    `Linux Kernel`_.  Otherwise, it's turned off by default.
+
+
+  * ``--fail-no-dbg``
+
+    Make the program fail and return a non-zero exit code if couldn't
+    read any of the debug information that comes from the debug info
+    packages that were given on the command line.  If no debug info
+    package were provided on the command line then this option is not
+    active.
+
+    Note that the non-zero exit code returned by the program as a
+    result of this option is the constant ``ABIDIFF_ERROR``.  To know
+    the numerical value of that constant, please refer to the
+    :ref:`exit code documentation <abidiff_return_value_label>`.
+
+
+  * ``--full-impact|-f``
+
+    When comparing two Linux Kernel packages, this function instructs
+    ``abipkgdiff`` to emit the so-called ``full impact report``, which
+    is the default report kind emitted by the ``abidiff`` tool: ::
+
+	$ abidiff libtest-v0.so libtest-v1.so
+	Functions changes summary: 0 Removed, 1 Changed, 0 Added function
+	Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
+
+	1 function with some indirect sub-type change:
+
+	  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
+	    parameter 1 of type 'C&' has sub-type changes:
+	      in referenced type 'struct C' at test-v1.cc:7:1:
+		type size hasn't changed
+		1 data member change:
+		 type of 'leaf* C::m0' changed:
+		   in pointed to type 'struct leaf' at test-v1.cc:1:1:
+		     type size changed from 32 to 64 bits
+		     1 data member insertion:
+		       'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
+
+	$
+
+
+  * ``--harmless``
+
+    In the diff report, display only the :ref:`harmless
+    <harmlesschangeconcept_label>` changes.  By default, the harmless
+    changes are filtered out of the diff report keep the clutter to a
+    minimum and have a greater chance to spot real ABI issues.
+
+
+  * ``--help | -h``
+
+    Display a short help about the command and exit.
+
+
+  * ``--impacted-interfaces``
+
+    When showing leaf changes, this option instructs abipkgdiff to
+    show the list of impacted interfaces.  This option is thus to be
+    used in addition to the ``--leaf-changes-only`` option, or, when
+    comparing two Linux Kernel packages.  Otherwise, it's simply
+    ignored.
+
+
+  * ``--keep-tmp-files``
+
+    Do not erase the temporary directory files that are created during
+    the execution of the tool.
 
-    Please note that the fact that (by default) ``abipkgdiff`` skips
-    private DSO is a feature that is available only for RPMs, at the
-    moment.  We would happily accept patches adding that feature for
-    other package formats.
 
   * ``--leaf-changes-only|-l`` only show leaf changes, so don't show
     impact analysis report.  This option implies ``--redundant``
@@ -228,149 +344,83 @@  Options
     option ``--full-impact`` which is documented later below.
 
 
-  * ``--impacted-interfaces``
-
-    When showing leaf changes, this option instructs abipkgdiff to
-    show the list of impacted interfaces.  This option is thus to be
-    used in addition to the ``--leaf-changes-only`` option, or, when
-    comparing two Linux Kernel packages.  Otherwise, it's simply
-    ignored.
+  * ``--linux-kernel-abi-whitelist | -w`` <*path-to-whitelist*>
 
-  * ``--full-impact|-f``
+    When comparing two Linux kernel RPM packages, this option points
+    to the white list of names of ELF symbols of functions and
+    variables that must be compared for ABI changes.  That white list
+    is called a "Linux kernel ABI white list".
 
-    When comparing two Linux Kernel packages, this function instructs
-    ``abipkgdiff`` to emit the so-called ``full impact report``, which
-    is the default report kind emitted by the ``abidiff`` tool: ::
+    Any other function or variable which ELF symbol are not present in
+    that white list will not be considered by the ABI comparison
+    process.
 
-	$ abidiff libtest-v0.so libtest-v1.so
-	Functions changes summary: 0 Removed, 1 Changed, 0 Added function
-	Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
+    If this option is not provided -- thus if no white list is
+    provided -- then the ABI of all publicly defined and exported
+    functions and global variables by the Linux Kernel binaries are
+    compared.
 
-	1 function with some indirect sub-type change:
+    Please note that if a white list package is given in parameter,
+    this option handles it just fine, like if the --wp option was
+    used.
 
-	  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
-	    parameter 1 of type 'C&' has sub-type changes:
-	      in referenced type 'struct C' at test-v1.cc:7:1:
-		type size hasn't changed
-		1 data member change:
-		 type of 'leaf* C::m0' changed:
-		   in pointed to type 'struct leaf' at test-v1.cc:1:1:
-		     type size changed from 32 to 64 bits
-		     1 data member insertion:
-		       'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
 
-	$
+  * ``--no-abignore``
 
+    Do not search the package for the presence of suppression files.
 
-  * ``--non-reachable-types|-t``
 
-    Analyze and emit change reports for all the types of the binary,
-    including those that are not reachable from global functions and
-    variables.
+  * ``--no-added-binaries``
 
-    This option might incur some serious performance degradation as
-    the number of types analyzed can be huge.  However, if paired with
-    the ``--devel-pkg{1,2}`` options, the additional non-reachable
-    types analyzed are restricted to those defined in the public
-    headers files carried by the referenced development packages, thus
-    hopefully making the performance hit acceptable.
+    Do not show the list of binaries that got added to the second
+    package.
 
-    Also, using this option alongside suppression specifications (by
-    also using the ``--suppressions`` option) might help keep the number of
-    analyzed types (and the potential performance degradation) in
-    control.
+    Please note that the presence of such added binaries is not
+    considered like an ABI change by this tool; as such, it doesn't
+    have any impact on the exit code of the tool.  It does only have
+    an informational value.  Removed binaries are, however, considered
+    as an ABI change.
 
-    Note that without this option, only types that are reachable from
-    global functions and variables are analyzed, so the tool detects
-    and reports changes on these reachable types only.
 
-  * ``--exported-interfaces-only``
+  * ``--no-added-syms``
 
-    By default, when looking at the debug information accompanying a
-    binary, this tool analyzes the descriptions of the types reachable
-    by the interfaces (functions and variables) that are visible
-    outside of their translation unit.  Once that analysis is done, an
-    ABI corpus is constructed by only considering the subset of types
-    reachable from interfaces associated to `ELF`_ symbols that are
-    defined and exported by the binary.  It's those final ABI Corpora
-    that are compared by this tool.
+    Do not show the list of functions, variables, or any symbol that
+    was added.
 
-    The problem with that approach however is that analyzing all the
-    interfaces that are visible from outside their translation unit
-    can amount to a lot of data, especially when those binaries are
-    applications, as opposed to shared libraries.  One example of such
-    applications is the `Linux Kernel`_.  Analyzing massive ABI
-    corpora like these can be extremely slow.
 
-    To mitigate that performance issue, this option allows libabigail
-    to only analyze types that are reachable from interfaces
-    associated with defined and exported `ELF`_ symbols.
+  * ``--no-assume-odr-for-cplusplus``
 
-    Note that this option is turned on by default when analyzing the
-    `Linux Kernel`_.  Otherwise, it's turned off by default.
+    When analysing a binary originating from C++ code using `DWARF`_
+    debug information, libabigail assumes the `One Definition Rule`_
+    to speed-up the analysis.  In that case, when several types have
+    the same name in the binary, they are assumed to all be equal.
 
-  * ``--allow-non-exported-interfaces``
+    This option disables that assumption and instructs libabigail to
+    actually actually compare the types to determine if they are
+    equal.
 
-    When looking at the debug information accompanying a binary, this
-    tool analyzes the descriptions of the types reachable by the
-    interfaces (functions and variables) that are visible outside of
-    their translation unit.  Once that analysis is done, an ABI corpus
-    is constructed by only considering the subset of types reachable
-    from interfaces associated to `ELF`_ symbols that are defined and
-    exported by the binary.  It's those final ABI Corpora that are
-    compared by this tool.
 
-    The problem with that approach however is that analyzing all the
-    interfaces that are visible from outside their translation unit
-    can amount to a lot of data, especially when those binaries are
-    applications, as opposed to shared libraries.  One example of such
-    applications is the `Linux Kernel`_.  Analyzing massive ABI
-    Corpora like these can be extremely slow.
+  * ``--no-default-suppression``
 
-    In the presence of an "average sized" binary however one can
-    afford having libabigail analyze all interfaces that are visible
-    outside of their translation unit, using this option.
+    Do not load the :ref:`default suppression specification files
+    <abipkgdiff_default_supprs_label>`.
 
-    Note that this option is turned on by default, unless we are in
-    the presence of the `Linux Kernel`_.
 
-  *  ``--redundant``
+  * ``--no-leverage-dwarf-factorization``
 
-    In the diff reports, do display redundant changes.  A redundant
-    change is a change that has been displayed elsewhere in a given
-    report.
+    When analysing a binary which `DWARF`_ debug information was
+    processed with the `DWZ`_ tool, the type information is supposed
+    to be already factorized.  That context is used by libabigail to
+    perform some speed optimizations.
 
-  * ``--harmless``
+    This option disables those optimizations.
 
-    In the diff report, display only the :ref:`harmless
-    <harmlesschangeconcept_label>` changes.  By default, the harmless
-    changes are filtered out of the diff report keep the clutter to a
-    minimum and have a greater chance to spot real ABI issues.
 
   * ``--no-linkage-name``
 
     In the resulting report, do not display the linkage names of
     the added, removed, or changed functions or variables.
 
-  * ``--no-added-syms``
-
-    Do not show the list of functions, variables, or any symbol that
-    was added.
-
-  * ``--no-added-binaries``
-
-    Do not show the list of binaries that got added to the second
-    package.
-
-    Please note that the presence of such added binaries is not
-    considered like an ABI change by this tool; as such, it doesn't
-    have any impact on the exit code of the tool.  It does only have
-    an informational value.  Removed binaries are, however, considered
-    as an ABI change.
-
-  * ``--no-abignore``
-
-    Do not search the package for the presence of suppression files.
 
   * ``--no-parallel``
 
@@ -378,71 +428,43 @@  Options
     execute concurrently.  This option tells it not to extract packages or run
     comparisons in parallel.
 
-  * ``--no-default-suppression``
-
-    Do not load the :ref:`default suppression specification files
-    <abipkgdiff_default_supprs_label>`.
-
-  * ``--suppressions | --suppr`` <*path-to-suppressions*>
-
-    Use a :ref:`suppression specification <suppr_spec_label>` file
-    located at *path-to-suppressions*.  Note that this option can
-    appear multiple times on the command line.  In that case, all of
-    the suppression specification files are taken into account.
-
-    Please note that, by default, if this option is not provided, then
-    the :ref:`default suppression specification files
-    <abipkgdiff_default_supprs_label>` are loaded .
 
-  * ``--linux-kernel-abi-whitelist | -w`` <*path-to-whitelist*>
+  * ``--non-reachable-types|-t``
 
-    When comparing two Linux kernel RPM packages, this option points
-    to the white list of names of ELF symbols of functions and
-    variables that must be compared for ABI changes.  That white list
-    is called a "Linux kernel ABI white list".
+    Analyze and emit change reports for all the types of the binary,
+    including those that are not reachable from global functions and
+    variables.
 
-    Any other function or variable which ELF symbol are not present in
-    that white list will not be considered by the ABI comparison
-    process.
+    This option might incur some serious performance degradation as
+    the number of types analyzed can be huge.  However, if paired with
+    the ``--devel-pkg{1,2}`` options, the additional non-reachable
+    types analyzed are restricted to those defined in the public
+    headers files carried by the referenced development packages, thus
+    hopefully making the performance hit acceptable.
 
-    If this option is not provided -- thus if no white list is
-    provided -- then the ABI of all publicly defined and exported
-    functions and global variables by the Linux Kernel binaries are
-    compared.
+    Also, using this option alongside suppression specifications (by
+    also using the ``--suppressions`` option) might help keep the number of
+    analyzed types (and the potential performance degradation) in
+    control.
 
-    Please note that if a white list package is given in parameter,
-    this option handles it just fine, like if the --wp option was
-    used.
+    Note that without this option, only types that are reachable from
+    global functions and variables are analyzed, so the tool detects
+    and reports changes on these reachable types only.
 
-  * ``--wp`` <*path-to-whitelist-package*>
 
-    When comparing two Linux kernel RPM packages, this option points
-    an RPM package containining several white lists of names of ELF
-    symbols of functions and variables that must be compared for ABI
-    changes.  Those white lists are called "Linux kernel ABI white
-    lists".
+  * ``--no-show-locs``
 
-    From the content of that white list package, this program then
-    chooses the appropriate Linux kernel ABI white list to consider
-    when comparing the ABI of Linux kernel binaries contained in the
-    Linux kernel packages provided on the command line.
+   Do not show information about where in the *second shared library*
+   the respective type was changed.
 
-    That choosen Linux kernel ABI white list contains the list of
-    names of ELF symbols of functions and variables that must be
-    compared for ABI changes.
 
-    Any other function or variable which ELF symbol are not present in
-    that white list will not be considered by the ABI comparison
-    process.
+  * ``--no-show-relative-offset-changes``
 
-    Note that this option can be provided twice (not mor than twice),
-    specifying one white list package for each Linux Kernel package
-    that is provided on the command line.
+     Without this option, when the offset of a data member changes,
+     the change report not only mentions the older and newer offset,
+     but it also mentions by how many bits the data member changes.
+     With this option, the latter is not shown.
 
-    If this option is not provided -- thus if no white list is
-    provided -- then the ABI of all publicly defined and exported
-    functions and global variables by the Linux Kernel binaries are
-    compared.
 
   * ``--no-unreferenced-symbols``
 
@@ -451,37 +473,30 @@  Options
     information.  Note that for these symbols not referenced by any
     debug information, the change information displayed is either
     added or removed symbols.
-    
-  * ``--no-show-locs``
 
-   Do not show information about where in the *second shared library*
-   the respective type was changed.
-
-  * ``--show-bytes``
-
-    Show sizes and offsets in bytes, not bits.  By default, sizes and
-    offsets are shown in bits.
 
   * ``--show-bits``
 
     Show sizes and offsets in bits, not bytes.  This option is
     activated by default.
 
-  * ``--show-hex``
 
-    Show sizes and offsets in hexadecimal base.
+  * ``--show-bytes``
+
+    Show sizes and offsets in bytes, not bits.  By default, sizes and
+    offsets are shown in bits.
+
 
   * ``--show-dec``
 
     Show sizes and offsets in decimal base.  This option is activated
     by default.
 
-  *  ``--no-show-relative-offset-changes``
 
-     Without this option, when the offset of a data member changes,
-     the change report not only mentions the older and newer offset,
-     but it also mentions by how many bits the data member changes.
-     With this option, the latter is not shown.
+  * ``--show-hex``
+
+    Show sizes and offsets in hexadecimal base.
+
 
   * ``--show-identical-binaries``
 
@@ -490,33 +505,27 @@  Options
    not provided, only binaries with ABI changes are mentionned in the
    output.
 
-  * ``--fail-no-dbg``
-
-    Make the program fail and return a non-zero exit code if couldn't
-    read any of the debug information that comes from the debug info
-    packages that were given on the command line.  If no debug info
-    package were provided on the command line then this option is not
-    active.
 
-    Note that the non-zero exit code returned by the program as a
-    result of this option is the constant ``ABIDIFF_ERROR``.  To know
-    the numerical value of that constant, please refer to the
-    :ref:`exit code documentation <abidiff_return_value_label>`.
-
-  * ``--keep-tmp-files``
+  * ``--private-dso``
 
-    Do not erase the temporary directory files that are created during
-    the execution of the tool.
+    By default, ``abipkgdiff`` does not compare DSOs that are private
+    to the RPM package.  A private DSO is a DSO which SONAME is *NOT*
+    advertised in the "provides" property of the RPM.
 
-  * ``--verbose``
+    This option instructs ``abipkgdiff`` to *also* compare DSOs that
+    are *NOT* advertised in the "provides" property of the RPM.
 
-    Emit verbose progress messages.
+    Please note that the fact that (by default) ``abipkgdiff`` skips
+    private DSO is a feature that is available only for RPMs, at the
+    moment.  We would happily accept patches adding that feature for
+    other package formats.
 
 
-  * ``--verbose-diff``
+  *  ``--redundant``
 
-    Emit timed verbose progress messages about the diffing process.
-    This option implies the --verbose one.
+    In the diff reports, do display redundant changes.  A redundant
+    change is a change that has been displayed elsewhere in a given
+    report.
 
 
   * ``--self-check``
@@ -534,36 +543,66 @@  Options
       $ abipkgdiff --self-check --d1 mesa-libGLU-debuginfo-9.0.1-3.fc33.x86_64.rpm  mesa-libGLU-9.0.1-3.fc33.x86_64.rpm
        ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
       $
-  * ``--no-assume-odr-for-cplusplus``
 
-    When analysing a binary originating from C++ code using `DWARF`_
-    debug information, libabigail assumes the `One Definition Rule`_
-    to speed-up the analysis.  In that case, when several types have
-    the same name in the binary, they are assumed to all be equal.
 
-    This option disables that assumption and instructs libabigail to
-    actually actually compare the types to determine if they are
-    equal.
+  * ``--suppressions | --suppr`` <*path-to-suppressions*>
 
-  * ``--no-leverage-dwarf-factorization``
+    Use a :ref:`suppression specification <suppr_spec_label>` file
+    located at *path-to-suppressions*.  Note that this option can
+    appear multiple times on the command line.  In that case, all of
+    the suppression specification files are taken into account.
 
-    When analysing a binary which `DWARF`_ debug information was
-    processed with the `DWZ`_ tool, the type information is supposed
-    to be already factorized.  That context is used by libabigail to
-    perform some speed optimizations.
+    Please note that, by default, if this option is not provided, then
+    the :ref:`default suppression specification files
+    <abipkgdiff_default_supprs_label>` are loaded .
 
-    This option disables those optimizations.
 
+  * `--version | -v`
+
+    Display the version of the program and exit.
 
-  * ``--ctf``
 
-     This is used to compare packages with `CTF`_ debug information,
-     if present.
+  * ``--wp`` <*path-to-whitelist-package*>
 
-  * ``--btf``
+    When comparing two Linux kernel RPM packages, this option points
+    an RPM package containining several white lists of names of ELF
+    symbols of functions and variables that must be compared for ABI
+    changes.  Those white lists are called "Linux kernel ABI white
+    lists".
+
+    From the content of that white list package, this program then
+    chooses the appropriate Linux kernel ABI white list to consider
+    when comparing the ABI of Linux kernel binaries contained in the
+    Linux kernel packages provided on the command line.
+
+    That choosen Linux kernel ABI white list contains the list of
+    names of ELF symbols of functions and variables that must be
+    compared for ABI changes.
+
+    Any other function or variable which ELF symbol are not present in
+    that white list will not be considered by the ABI comparison
+    process.
+
+    Note that this option can be provided twice (not mor than twice),
+    specifying one white list package for each Linux Kernel package
+    that is provided on the command line.
+
+    If this option is not provided -- thus if no white list is
+    provided -- then the ABI of all publicly defined and exported
+    functions and global variables by the Linux Kernel binaries are
+    compared.
+
+
+  * ``--verbose``
+
+    Emit verbose progress messages.
+
+
+  * ``--verbose-diff``
+
+    Emit timed verbose progress messages about the diffing process.
+    This option implies the --verbose one.
 
-     This is used to compare packages with `BTF`_ debug information,
-     if present.
 
 .. _abipkgdiff_return_value_label: