From 19e4fcd379eb9a20e181f5d6842e67b385718634 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Tue, 18 Jun 2024 21:45:19 -0600 Subject: [PATCH] perlapi: Show prototypes for all elements Some functions/macros are grouped together in a single entry where those items are just variants of each other. This makes it is easier for the reader to choose the variant that is best for their current purpose. Prior to this commit if the return type and parameters to all variants in the group were the same, only the first item's prototype gets displayed. This was to save space. But I have found myself searching in vain for a prototype that was squashed, and it's not a whole lot of space that gets saved. This commit displays the signatures of all elements of a group. It doesn't change that trivial signatures are omitted. These are when just the name itself of the macro or typedef would be displayed, with no adornment. Displaying these actually is confusing, because there is no context for the name. --- autodoc.pl | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/autodoc.pl b/autodoc.pl index 608d629447e9..a635416f5c22 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -1440,11 +1440,9 @@ ($$$) && $item->{name} =~ /^Perl_/; } - # Look through all the items in this entry. If all have the same - # return type and arguments (including thread context), only the - # main entry is displayed. - # Also, find the longest return type and longest name so that if - # multiple ones are shown, they can be vertically aligned nicely + # Look through all the items in this entry. Find the longest + # return type and longest name so that if multiple ones are shown, + # they can be nicely vertically aligned. my $need_individual_usage = 0; my $longest_name_length = length $items[0]->{name}; my $base_ret_type = $items[0]->{ret_type}; @@ -1453,13 +1451,6 @@ ($$$) my $base_thread_context = $items[0]->{flags} =~ /T/; for (my $i = 1; $i < @items; $i++) { my $item = $items[$i]; - my $args_are_equal = $item->{args}->@* == @base_args - && !grep $item->{args}[$_] ne $base_args[$_], keys @base_args; - $need_individual_usage = 1 - if $item->{ret_type} ne $base_ret_type - || ! $args_are_equal - || ( $item->{flags} =~ /T/ - != $base_thread_context); my $ret_length = length $item->{ret_type}; $longest_ret = $ret_length if $ret_length > $longest_ret; my $name_length = length $item->{name}; @@ -1467,9 +1458,6 @@ ($$$) if $name_length > $longest_name_length; } - # If we're only showing one entry, only its length matters. - $longest_name_length = length($items[0]->{name}) - unless $need_individual_usage; print $fh "\n"; my $indent = 1; # 1 is sufficient for verbatim; =over is used @@ -1586,9 +1574,6 @@ ($$$) print $fh ";" if $item_flags =~ /;/; # semicolon: "dTHR;" print $fh "\n"; - - # Only the first entry is normally displayed - last unless $need_individual_usage; } } @@ -1982,10 +1967,7 @@ sub add_defn { |serves for multiple functions which all do basically the same thing, but have |some slight differences. For example, one form might process magic, while |another doesn't. The name of each variation is listed at the top of the -|single entry. But if all have the same signature (arguments and return type) -|except for their names, only the usage for the base form is shown. If any -|one of the forms has a different signature (such as returning C or -|not) every function's signature is explicitly displayed. +|single entry. | |Anything not listed here or in the other mentioned pods is not part of the |public API, and should not be used by extension writers at all. For these