Skip to content

Commit

Permalink
perlapi: Show prototypes for all elements
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
khwilliamson committed Jun 22, 2024
1 parent 9141665 commit 19e4fcd
Showing 1 changed file with 4 additions and 22 deletions.
26 changes: 4 additions & 22 deletions autodoc.pl
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand All @@ -1453,23 +1451,13 @@ ($$$)
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};
$longest_name_length = $name_length
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
Expand Down Expand Up @@ -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;
}
}

Expand Down Expand Up @@ -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<const> 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
Expand Down

0 comments on commit 19e4fcd

Please sign in to comment.