From 2306c73564c79c1b0b653d25b019d63f3415c36d Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Mon, 29 Jul 2024 07:29:14 -0600 Subject: [PATCH] autodoc: Add an Index section perlapi and perlintern are divided into sections that partition the API elements into rough major categories of related functions. This commit causes an Index to be generated, a mapping from function name to the section it's documented in. --- autodoc.pl | 76 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 60 insertions(+), 16 deletions(-) diff --git a/autodoc.pl b/autodoc.pl index 86f93b4f21e1..cf5106549d37 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -158,6 +158,10 @@ # unlooked at my %protos; +# For outputting an index of the API elements. Each key is an element; its +# value is the section the element is in. +my %index; + my $described_in = "Described in"; my $description_indent = 4; @@ -231,6 +235,7 @@ # Kept separate at end my $undocumented_scn = 'Undocumented elements'; +my $index_scn = 'INDEX'; my %valid_sections = ( $AV_scn => {}, @@ -479,10 +484,11 @@ ($file, $line_num = 0) return "at $file, line $line_num"; } -sub check_and_add_proto_defn { - my ($element, $file, $line_num, $raw_flags, $ret_type, $args_ref, - $definition_type - ) = @_; +sub check_and_add_proto_defn($element, $file, $line_num, $destpod, $section, + $raw_flags, $ret_type, $args_ref, + $definition_type) +{ + # This function constructs a hash describing what we know so far about the # API element '$element', as determined by 'apidoc'-type lines scattered @@ -620,6 +626,16 @@ sub check_and_add_proto_defn { else { $elements{$element}{docs_found}{file} = $file; $elements{$element}{docs_found}{line_num} = $line_num // 0; + $elements{$element}{docs_found}{section} = $section; + + if (! $destpod) { + my $this_flags = $elements{$element}{flags} + || $flags_sans_d; + $destpod = destination_pod($this_flags); + } + + $elements{$element}{destpod} = $destpod; + $index{$destpod}{$element} = $section; } if ($definition_type == PLAIN_APIDOC) { @@ -758,7 +774,7 @@ ($file, $line_num, $input, $is_file_C) EOS } -sub handle_apidoc_line ($file, $line_num, $type, $arg) { +sub handle_apidoc_line ($file, $line_num, $destpod, $section, $type, $arg) { # This just does a couple of checks that would otherwise have to be # duplicated in the calling code, and calls check_and_add_proto_defn() to @@ -792,10 +808,12 @@ ($file, $line_num, $type, $arg) # this definition (which has the side effect of cleaning up any NN or # NULLOK in @args) my $updated = check_and_add_proto_defn($name, $file, $line_num, + $destpod, $section, # The fact that we have this line somewhere in the source # code means we implicitly have the 'd' flag $flags . "d", + $ret_type, \@args, $type); @@ -899,7 +917,8 @@ ($fh, $file) . " '$arg' " . where_from_string($file, $line_num); } elsif ($outer_line_type == APIDOC_DEFN) { - handle_apidoc_line($file, $line_num, $outer_line_type, $arg); + handle_apidoc_line($file, $line_num, $destpod, $section, + $outer_line_type, $arg); next; # 'handle_apidoc_line' handled everything for this type } elsif ($outer_line_type == APIDOC_SECTION) { @@ -920,9 +939,10 @@ ($fh, $file) # Drop down to accumulate the heading text for this section. } elsif ($outer_line_type == PLAIN_APIDOC) { - my $leader_ref = - handle_apidoc_line($file, $line_num, $outer_line_type, $arg); - $destpod = destination_pod($$leader_ref->{flags}); + my $leader_ref = handle_apidoc_line($file, $line_num, + undef, $section, + $outer_line_type, $arg); + $destpod = $$leader_ref->{destpod}; push @items, $leader_ref; @@ -944,8 +964,9 @@ ($fh, $file) # separating 'apidoc_item' lines $text = ""; - my $item_ref = - handle_apidoc_line($file, $line_num, $item_line_type, $arg); + my $item_ref = handle_apidoc_line($file, $line_num, + $destpod, $section, + $item_line_type, $arg); push @items, $item_ref; } @@ -1563,6 +1584,7 @@ sub parse_config_h { $flags .= 'U' unless defined $configs{$name}{usage}; my $data = check_and_add_proto_defn($name, $config_h, $configs{$name}{defn_line_num}, + $api, $section, $flags, "void", # No return type [], @@ -2336,6 +2358,24 @@ ($destpod) print $fh construct_missings_section($hdr, $ref); } + print $fh <<~EOT; + + =head1 $index_scn + + Below is an alphabetical list of all API elements in this file, + cross referenced to the section in which they are documented. + + EOT + + my %this_index = $index{$podname}->%*; + my $space = "E" x 4; + + print $fh "=over 1\n\n"; + foreach my $element (sort dictionary_order keys %this_index) { + print $fh "=item L${space}L\n\n"; + } + print $fh "=back\n\n"; + print $fh "\n$destpod->{footer}\n=cut\n"; read_only_bottom_close_and_rename($fh); @@ -2350,7 +2390,10 @@ ($destpod) @{$embed}{qw(flags return_type name args)}; check_and_add_proto_defn($func, $file, # embed.fnc data doesn't currently furnish the - # line number + # line number; and we have no section in the + # documente yet + undef, + undef, undef, $flags, $ret_type, $args, @@ -2593,7 +2636,8 @@ ($destpod) my $section_list = join "\n\n", map { "=item L" } sort(dictionary_order keys %valid_sections), - $undocumented_scn; # Keep last + $undocumented_scn, # Keep next-to-last + $index_scn; # Keep last # Leading '|' is to hide these lines from pod checkers. khw is unsure if this # is still needed. @@ -2613,9 +2657,9 @@ ($destpod) |L and F<$config_h>, some items are listed here as being actually |documented in another pod. | -|L is a list of functions which have yet -|to be documented. Patches welcome! The interfaces of these are subject to -|change without notice. +|L is a list of functions which have +|yet to be documented. Patches welcome! The interfaces of these are subject +|to change without notice. | |Some of the functions documented here are consolidated so that a single entry |serves for multiple functions which all do basically the same thing, but have