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