From 2aa73c643cc3dde35932f5e6209f50ca2f28fc93 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Fri, 24 Jun 2022 13:12:23 -0600 Subject: perlapi: Ensure ref-only items have X<> Some minor API elements, such as flag values, in perlapi are mentioned only in passing in the pod of some encompassing element. This commit makes sure those minor elements have a X<> pod element generated for them in the appropriate place. This makes sure that other code that, say, indexes the API knows whereabouts to link, etc. to. --- autodoc.pl | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'autodoc.pl') diff --git a/autodoc.pl b/autodoc.pl index 565cc9c340..c45f7a115e 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -643,17 +643,19 @@ sub autodoc ($$) { # parse a file and extract documentation info die "No =for apidoc_section nor =head1 in $file for '$element_name'\n" unless defined $section; - if (exists $docs{$where}{$section}{$element_name}) { + my $is_link_only = ($flags =~ /h/); + if (! $is_link_only && exists $docs{$where}{$section}{$element_name}) { warn "$0: duplicate API entry for '$element_name' in" . " $where/$section\n"; next; } # Override the text with just a link if the flags call for that - my $is_link_only = ($flags =~ /h/); if ($is_link_only) { if ($file_is_C) { - die "Can't currently handle link with items to it:\n$in" if @items; + die "Can't currently handle link with items to it:\n$in" + if @items; + $docs{$where}{$section}{X_tags}{$element_name} = $file; redo; # Don't put anything if C source } @@ -1691,6 +1693,12 @@ sub output { print $fh "\n=head1 $section_name\n"; + if ($section_info->{X_tags}) { + print $fh "X<$_>" for keys $section_info->{X_tags}->%*; + print $fh "\n"; + delete $section_info->{X_tags}; + } + if ($podname eq 'perlapi') { print $fh "\n", $valid_sections{$section_name}{header}, "\n" if defined $valid_sections{$section_name}{header}; @@ -1709,7 +1717,9 @@ sub output { } } else { - print $fh "\nThere are only public API items currently in $section_name\n"; + my $pod_type = ($podname eq 'api') ? "public" : "internal"; + print $fh "\nThere are currently no $pod_type API items in ", + $section_name, "\n"; } print $fh "\n", $valid_sections{$section_name}{footer}, "\n" -- cgit v1.2.1