doc/check_docs.py

   1 #!/usr/bin/env python
   2
   3 import sys, glob
   4
   5 sys.path.append("../modules/python/src2/")
   6 import hdr_parser as hp
   7
   8 opencv_hdr_list = [
   9 "../modules/core/include/opencv2/core.hpp",
  10 "../modules/ml/include/opencv2/ml.hpp",
  11 "../modules/imgproc/include/opencv2/imgproc.hpp",
  12 "../modules/calib3d/include/opencv2/calib3d.hpp",
  13 "../modules/features2d/include/opencv2/features2d.hpp",
  14 "../modules/video/include/opencv2/video/tracking.hpp",
  15 "../modules/video/include/opencv2/video/background_segm.hpp",
  16 "../modules/objdetect/include/opencv2/objdetect.hpp",
  17 "../modules/highgui/include/opencv2/highgui.hpp",
  18 ]
  19
  20 opencv_module_list = [
  21 "core",
  22 "imgproc",
  23 "calib3d",
  24 "features2d",
  25 "video",
  26 "objdetect",
  27 "highgui",
  28 "ml"
  29 ]
  30
  31 class RSTParser(object):
  32
  33     def __init__(self):
  34         self.read_whitelist()
  35
  36     # reads the file containing functions and classes that do not need to be documented
  37     def read_whitelist(self):
  38         self.whitelist = {}
  39         try:
  40             wf = open("check_docs_whitelist.txt", "rt")
  41         except IOError:
  42             return
  43         self.parser = hp.CppHeaderParser()
  44
  45         for l in wf.readlines():
  46             cpos = l.find("#")
  47             if cpos >= 0:
  48                 l = l[:cpos]
  49             l = l.strip()
  50             if not l:
  51                 continue
  52             rst_decl = None
  53             if "(" in l:
  54                 l = l.replace("cv::", "")
  55                 rst_decl = self.parser.parse_func_decl_no_wrap(l)
  56                 fname = rst_decl[0]
  57             else:
  58                 fname = l.replace("::", ".")
  59             complist = fname.split(".")
  60             prefix = ""
  61             alreadyListed = False
  62             wl = []
  63             for c in complist:
  64                 prefix = (prefix + "." + c).lstrip(".")
  65                 wl = self.whitelist.get(prefix, [])
  66                 if wl == "*":
  67                     break
  68             if wl == "*":
  69                 continue
  70             if not rst_decl:
  71                 self.whitelist[fname] = "*"
  72             else:
  73                 wl.append(rst_decl)
  74                 self.whitelist[fname] = wl
  75         wf.close()
  76
  77     def process_rst(self, docname):
  78         df = open(docname, "rt")
  79         fdecl = ""
  80         balance = 0
  81         lineno = 0
  82
  83         for l in df.readlines():
  84             lineno += 1
  85             ll = l.strip()
  86             if balance == 0:
  87                 if not ll.startswith(".. c:function::") and \
  88                    not ll.startswith(".. cpp:function::") and \
  89                    not ll.startswith(".. ocv:function::") and \
  90                    not ll.startswith(".. ocv:cfunction::"):
  91                     continue
  92                 fdecl = ll[ll.find("::") + 3:]
  93             elif balance > 0:
  94                 fdecl += ll
  95             balance = fdecl.count("(") - fdecl.count(")")
  96             assert balance >= 0
  97             if balance > 0:
  98                 continue
  99             rst_decl = self.parser.parse_func_decl_no_wrap(fdecl)
 100             fname = rst_decl[0]
 101             hdr_decls = self.fmap.get(fname, [])
 102             if not hdr_decls:
 103                 fname = fname.replace("cv.", "")
 104                 hdr_decls = self.fmap.get(fname, [])
 105             if not hdr_decls:
 106                 print "Documented function %s (%s) in %s:%d is not in the headers" % (fdecl, rst_decl[0].replace(".", "::"), docname, lineno)
 107                 continue
 108             decl_idx = 0
 109             for hd in hdr_decls:
 110                 if len(hd[3]) != len(rst_decl[3]):
 111                     decl_idx += 1
 112                     continue
 113                 idx = 0
 114                 for a in hd[3]:
 115                     if a[0] != rst_decl[3][idx][0] and a[0].replace("cv::", "") != rst_decl[3][idx][0]:
 116                         break
 117                     idx += 1
 118                 if idx == len(hd[3]):
 119                     break
 120                 decl_idx += 1
 121             if decl_idx < len(hdr_decls):
 122                 self.fmap[fname] = hdr_decls[:decl_idx] + hdr_decls[decl_idx+1:]
 123                 continue
 124             print "Documented function %s in %s:%d does not have a match" % (fdecl, docname, lineno)
 125         df.close()
 126
 127     def decl2str(self, decl):
 128         return "%s %s(%s)" % (decl[1], decl[0], ", ".join([a[0] + " " + a[1] for a in decl[3]]))
 129
 130     def check_module_docs(self, name):
 131         self.parser = hp.CppHeaderParser()
 132         decls = []
 133         self.fmap = {}
 134
 135         for hname in opencv_hdr_list:
 136             if hname.startswith("../modules/" + name):
 137                 decls += self.parser.parse(hname, wmode=False)
 138
 139         for d in decls:
 140             fname = d[0]
 141             if not fname.startswith("struct") and not fname.startswith("class") and not fname.startswith("const"):
 142                 dlist = self.fmap.get(fname, [])
 143                 dlist.append(d)
 144                 self.fmap[fname] = dlist
 145
 146         self.missing_docfunc_list = []
 147
 148         doclist = glob.glob("../modules/" + name + "/doc/*.rst")
 149         for d in doclist:
 150             self.process_rst(d)
 151
 152         print "\n\n########## The list of undocumented functions: ###########\n\n"
 153         misscount = 0
 154         fkeys = sorted(self.fmap.keys())
 155         for f in fkeys:
 156             # skip undocumented destructors
 157             if "~" in f:
 158                 continue
 159             decls = self.fmap[f]
 160             fcomps = f.split(".")
 161             prefix = ""
 162             wlist_decls = []
 163             for c in fcomps:
 164                 prefix = (prefix + "." + c).lstrip(".")
 165                 wlist_decls = self.whitelist.get(prefix, [])
 166                 if wlist_decls == "*":
 167                     break
 168             if wlist_decls == "*":
 169                 continue
 170             wlist_decls = [self.decl2str(d) for d in wlist_decls]
 171
 172             for d in decls:
 173                 dstr = self.decl2str(d)
 174                 # special hack for ML: skip old variants of the methods
 175                 if name == "ml" and ("CvMat" in dstr):
 176                     continue
 177                 if dstr not in wlist_decls:
 178                     misscount += 1
 179                     print "%s %s(%s)" % (d[1], d[0].replace(".", "::"), ", ".join([a[0] + " " + a[1] for a in d[3]]))
 180         print "\n\n\nundocumented functions in %s: %d" % (name, misscount)
 181
 182
 183 p = RSTParser()
 184 for m in opencv_module_list:
 185     print "\n\n*************************** " + m + " *************************\n"
 186     p.check_module_docs(m)