contrib/check-params-in-docs.py

   1 #!/usr/bin/env python3
   2
   3 # Copyright (C) 2018-2024 Free Software Foundation, Inc.
   4 #
   5 # Find missing and extra parameters in documentation compared to
   6 # output of: gcc --help=params.
   7 #
   8 # This file is part of GCC.
   9 #
  10 # GCC is free software; you can redistribute it and/or modify it under
  11 # the terms of the GNU General Public License as published by the Free
  12 # Software Foundation; either version 3, or (at your option) any later
  13 # version.
  14 #
  15 # GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  16 # WARRANTY; without even the implied warranty of MERCHANTABILITY or
  17 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  18 # for more details.
  19 #
  20 # You should have received a copy of the GNU General Public License
  21 # along with GCC; see the file COPYING3.  If not see
  22 # <http://www.gnu.org/licenses/>.
  23 #
  24 #
  25 #
  26
  27 import argparse
  28 import sys
  29 from itertools import dropwhile, takewhile
  30
  31
  32 def get_param_tuple(line):
  33     line = line.strip().replace('--param=', '')
  34     i = line.find(' ')
  35     name = line[:i]
  36     if '=' in name:
  37         name = name[:name.find('=')]
  38     description = line[i:].strip()
  39     return (name, description)
  40
  41 def target_specific(param):
  42     return param.split('-')[0] in ('aarch64', 'gcn', 'x86')
  43
  44
  45 parser = argparse.ArgumentParser()
  46 parser.add_argument('texi_file')
  47 parser.add_argument('params_output')
  48
  49 args = parser.parse_args()
  50
  51 ignored = {'logical-op-non-short-circuit'}
  52 help_params = {}
  53
  54 for line in open(args.params_output).readlines():
  55     if line.startswith(' ' * 2) and not line.startswith(' ' * 8):
  56         r = get_param_tuple(line)
  57         help_params[r[0]] = r[1]
  58
  59 # Skip target-specific params
  60 help_params = [x for x in help_params.keys() if not target_specific(x)]
  61
  62 # Find section in .texi manual with parameters
  63 texi = ([x.strip() for x in open(args.texi_file).readlines()])
  64 texi = dropwhile(lambda x: 'item --param' not in x, texi)
  65 texi = takewhile(lambda x: '@node Instrumentation Options' not in x, texi)
  66 texi = list(texi)[1:]
  67
  68 texi_params = []
  69 skip = False
  70 for line in texi:
  71     # Skip @table @samp sections of manual where values of a param are usually
  72     # listed
  73     if skip:
  74         if line.startswith('@end table'):
  75             skip = False
  76         continue
  77     elif line.startswith('@table @samp'):
  78         skip = True
  79         continue
  80
  81     for token in ('@item ', '@itemx '):
  82         if line.startswith(token):
  83             texi_params.append(line[len(token):])
  84             break
  85
  86 # Skip target-specific params
  87 texi_params = [x for x in texi_params if not target_specific(x)]
  88
  89 texi_set = set(texi_params) - ignored
  90 params_set = set(help_params) - ignored
  91
  92 success = True
  93 extra = texi_set - params_set
  94 if len(extra):
  95     print('Extra:')
  96     print(extra)
  97     success = False
  98
  99 missing = params_set - texi_set
 100 if len(missing):
 101     print('Missing:')
 102     for m in missing:
 103         print('@item ' + m)
 104         print(params[m])
 105         print()
 106     success = False
 107
 108 sys.exit(0 if success else 1)