opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-07-03 09:17:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

man-page xref: check for duplicate entries

Browse Source 
Check for duplicate subcommands, flags, and format specifiers.
I assumed this would never be necessary, that code review would
catch dups, but it happened (#19462). Prevent future ones.

Also, make it a fatal error for a --format to be undocumented,
except for 'podman inspect'. So many exceptions ... :(

Signed-off-by: Ed Santiago <santiago@redhat.com>
This commit is contained in:
Ed Santiago
2023-08-07 05:46:13 -06:00
parent c04ead152e
commit 819129b0d7
1 changed files with 26 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
hack/xref-helpmsgs-manpages
View File

@ -95,6 +95,13 @@ my %Format_Option_Is_Special = map { $_ => 1 } (
'inspect', # ambiguous (container/image) 'inspect', # ambiguous (container/image)
); );
# Hardcoded list of existing duplicate-except-for-case format codes,
# with their associated subcommands. Let's not add any more.
my %Format_Option_Dup_Allowed = (
'podman-images' => { '.id' => 1 },
'podman-stats' => { '.avgcpu' => 1, '.pids' => 1 },
);
# Do not cross-reference these. # Do not cross-reference these.
my %Skip_Subcommand = map { $_ => 1 } ( my %Skip_Subcommand = map { $_ => 1 } (
"help", # has no man page "help", # has no man page
@ -203,8 +210,7 @@ sub xref_by_help {
if ($k eq '--format' && ! ref($man->{$k})) { if ($k eq '--format' && ! ref($man->{$k})) {
warn "$ME: 'podman @subcommand': --format options are available through autocomplete, but are not documented in $man->{_path}\n"; warn "$ME: 'podman @subcommand': --format options are available through autocomplete, but are not documented in $man->{_path}\n";
# FIXME: don't make this an error... yet. ++$Errs unless "@subcommand" eq "inspect";
# ++$Errs;
next OPTION; next OPTION;
} }
@ -491,6 +497,10 @@ sub podman_man {
warn "$ME: $subpath:$.: '$previous_subcmd' and '$subcmd' are out of order\n"; warn "$ME: $subpath:$.: '$previous_subcmd' and '$subcmd' are out of order\n";
++$Errs; ++$Errs;
} }
if ($previous_subcmd eq $subcmd) {
warn "$ME: $subpath:$.: duplicate subcommand '$subcmd'\n";
++$Errs;
}
$previous_subcmd = $subcmd; $previous_subcmd = $subcmd;
$man{$subcmd} = podman_man($link_name); $man{$subcmd} = podman_man($link_name);
@ -529,6 +539,10 @@ sub podman_man {
warn "$ME: $subpath:$.: $flag should precede $previous_flag\n"; warn "$ME: $subpath:$.: $flag should precede $previous_flag\n";
++$Errs; ++$Errs;
} }
if ($flag eq $previous_flag) {
warn "$ME: $subpath:$.: flag '$flag' is a dup\n";
++$Errs;
}
$previous_flag = $flag if $is_first; $previous_flag = $flag if $is_first;
push @most_recent_flags, $flag; push @most_recent_flags, $flag;
@ -607,10 +621,20 @@ sub podman_man {
# too many subformats to document individually. # too many subformats to document individually.
$man{$previous_flag}{$format} = $etc || 1; $man{$previous_flag}{$format} = $etc || 1;
# Sort order check, case-insensitive
if (lc($format) lt lc($previous_format)) { if (lc($format) lt lc($previous_format)) {
warn "$ME: $subpath:$.: format specifier '$format' should precede '$previous_format'\n"; warn "$ME: $subpath:$.: format specifier '$format' should precede '$previous_format'\n";
++$Errs; ++$Errs;
} }
# Dup check, would've caught #19462.
if (lc($format) eq lc($previous_format)) {
# Sigh. Allow preexisting exceptions, but no new ones.
unless ($Format_Option_Dup_Allowed{$command}{lc $format}) {
warn "$ME: $subpath:$.: format specifier '$format' is a dup\n";
++$Errs;
}
}
$previous_format = $format; $previous_format = $format;
} }
} }