contrib/check-params-in-docs.py

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