Skip to content

perlapi/perlintern: Note binary-compatibility-only entries #23332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: blead
Choose a base branch
from
Open

perlapi/perlintern: Note binary-compatibility-only entries #23332

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 39 additions & 8 deletions autodoc.pl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,11 +77,11 @@
qr/[aA bC dD eE fF Gh iI mM nN oO pP rR sS T uU vW xX y;#?]/xx;

# Flags that don't apply to this program, like implementation details.
my $irrelevant_flags_re = qr/[ab eE G iI P rR vX?]/xx;
my $irrelevant_flags_re = qr/[a eE G iI P rR vX?]/xx;

# Only certain flags dealing with what gets displayed, are acceptable for
# apidoc_item
my $item_flags_re = qr/[dD fF mM nN oO pT uU Wx;]/xx;
my $item_flags_re = qr/[ b dD fF mM nN oO pT uU Wx; ]/xx;

use constant {
NOT_APIDOC => -1,
Expand Down Expand Up @@ -1625,6 +1625,7 @@ ($fh, $section_name, $element_name, $docref)
print $fh "\n=item C<${$_}->{name}>\n" for @items;

my @where_froms;
my @bin_compat;
my @deprecated;
my @experimental;
my @xrefs;
Expand All @@ -1642,8 +1643,15 @@ ($fh, $section_name, $element_name, $docref)
# entry, so no X<> here.
push @xrefs, $name unless $item->{flags} =~ /h/;

push @deprecated, "C<$name>" if $item->{flags} =~ /D/;
push @experimental, "C<$name>" if $item->{flags} =~ /x/;
if ($item->{flags} =~ /D/) {
push @deprecated, "C<$name>";
}
elsif ($item->{flags} =~ /b/) {
push @bin_compat, "C<$name>";
}
elsif ($item->{flags} =~ /x/) {
push @experimental, "C<$name>";
}
}

# While we're going though the items, construct a nice list of where
Expand Down Expand Up @@ -1695,7 +1703,7 @@ ($fh, $section_name, $element_name, $docref)
print $fh format_pod_indexes(\@xrefs);
print $fh "\n" if @xrefs;

for my $which (\@deprecated, \@experimental) {
for my $which (\@deprecated, \@experimental, \@bin_compat) {
next unless $which->@*;

my $is;
Expand Down Expand Up @@ -1731,6 +1739,13 @@ ($fh, $section_name, $element_name, $docref)
new code; remove $it from existing code.
EOT
}
elsif ($which == \@bin_compat) {
print $fh <<~"EOT";

C<B<DO NOT USE FOR NEW CODE!>> $list $is retained only so
that existing applications that use $it don't have to change.
EOT
}
else {
print $fh <<~"EOT";

Expand Down Expand Up @@ -2696,7 +2711,7 @@ ($destpod)
# documentation is missing

for my $which (\%api, \%intern) {
my (@deprecated, @experimental, @missings);
my (@deprecated, @experimental, @missings, @bin_compat);
for my $name (sort dictionary_order keys %elements) {
my $element = $elements{$name};

Expand Down Expand Up @@ -2724,6 +2739,9 @@ ($destpod)
elsif ($element->{flags} =~ /x/) {
push @experimental, $name;
}
elsif ($element->{flags} =~ /b/) {
push @bin_compat, $name;
}
else {
push @missings, $name;
}
Expand All @@ -2734,6 +2752,7 @@ ($destpod)
$which->{missings}->@* = (
missings_hdr => \@missings,
experimental_hdr => \@experimental,
bin_compat_hdr => \@bin_compat,
deprecated_hdr => \@deprecated,
);
}
Expand Down Expand Up @@ -2897,6 +2916,12 @@ ($destpod)
|usable by you.
_EOT_

$api{bin_compat_hdr} = <<"_EOT_";
|
|Next are the API-flagged elements that are retained only so that code that
|already uses them doesn't have to change. DO NOT ADD ANY NEW USES FOR THESE.
_EOT_

$api{experimental_hdr} = <<"_EOT_";
|
|Next are the API-flagged elements that are considered experimental. Using one
Expand Down Expand Up @@ -2949,9 +2974,15 @@ ($destpod)
|This section lists the elements that are otherwise undocumented. If you use
|any of them, please consider creating and submitting documentation for it.
|
|Experimental and deprecated undocumented elements are listed separately at the
|end.
|Elements that are problematic to use (such as being experimental) are listed
|separately at the end.
|
_EOT_

$intern{bin_compat_hdr} = <<"_EOT_";
|
|Next are the elements that are retained only so that code that already uses
|them doesn't have to change. DO NOT ADD ANY NEW USES FOR THESE.
_EOT_

$intern{experimental_hdr} = <<"_EOT_";
Expand Down
Loading