#! /usr/bin/env python3
# -*- coding: utf-8 -*-
-# Copyright (c) 2019. The SimGrid Team.
-# All rights reserved.
+# Copyright (c) 2019-2021. The SimGrid Team. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the terms of the license (GNU LGPL) which comes with this package.
"""
Search for symbols documented in both the XML files produced by Doxygen and the python modules,
-but not documented with autodoxy in the RST files.
+but not documented with breathe in the RST files.
-This script is tailored to SimGrid own needs and should be made more generic for autodoxy.
+This script is tailored to SimGrid own needs.
+
+If you are missing some dependencies, try: pip3 install --requirement docs/requirements.txt
"""
import fnmatch
import inspect
xml_files = [
-# 'build/xml/classsimgrid_1_1s4u_1_1Activity.xml',
+ 'build/xml/classsimgrid_1_1s4u_1_1Activity.xml',
'build/xml/classsimgrid_1_1s4u_1_1Actor.xml',
'build/xml/classsimgrid_1_1s4u_1_1Barrier.xml',
'build/xml/classsimgrid_1_1s4u_1_1Comm.xml',
'build/xml/classsimgrid_1_1s4u_1_1ConditionVariable.xml',
'build/xml/classsimgrid_1_1s4u_1_1Disk.xml',
'build/xml/classsimgrid_1_1s4u_1_1Engine.xml',
- 'build/xml/classsimgrid_1_1s4u_1_1ExecPar.xml',
- 'build/xml/classsimgrid_1_1s4u_1_1ExecSeq.xml',
'build/xml/classsimgrid_1_1s4u_1_1Exec.xml',
'build/xml/classsimgrid_1_1s4u_1_1Host.xml',
'build/xml/classsimgrid_1_1s4u_1_1Io.xml',
'build/xml/classsimgrid_1_1s4u_1_1Mutex.xml',
'build/xml/classsimgrid_1_1s4u_1_1NetZone.xml',
'build/xml/classsimgrid_1_1s4u_1_1Semaphore.xml',
- 'build/xml/classsimgrid_1_1s4u_1_1VirtualMachine.xml'
+ 'build/xml/classsimgrid_1_1s4u_1_1VirtualMachine.xml',
+ 'build/xml/classsimgrid_1_1xbt_1_1signal_3_01R_07P_8_8_8_08_4.xml',
+ 'build/xml/namespacesimgrid_1_1s4u_1_1this__actor.xml',
+ 'build/xml/actor_8h.xml',
+ 'build/xml/barrier_8h.xml',
+ 'build/xml/cond_8h.xml',
+ 'build/xml/engine_8h.xml',
+ 'build/xml/forward_8h.xml',
+ 'build/xml/host_8h.xml',
+ 'build/xml/link_8h.xml',
+ 'build/xml/mailbox_8h.xml',
+ 'build/xml/msg_8h.xml',
+ 'build/xml/mutex_8h.xml',
+ 'build/xml/semaphore_8h.xml',
+ 'build/xml/vm_8h.xml',
+ 'build/xml/zone_8h.xml'
]
python_modules = [
def found_decl(kind, obj):
"""Helper function that add an object in the python_decl data structure"""
- if not kind in python_decl: python_decl[kind] = []
+ if kind not in python_decl:
+ python_decl[kind] = []
python_decl[kind].append(obj)
try:
module = __import__(name)
except Exception:
- print("Cannot import {}. Did you set PYTHONPATH=../lib accordingly?".format(name))
- sys.exit(1)
+ if os.path.exists("../lib") and "../lib" not in sys.path:
+ print("Adding ../lib to PYTHONPATH as {} cannot be imported".format(name))
+ sys.path.append("../lib")
+ try:
+ module = __import__(name)
+ except Exception:
+ print("Cannot import {}, even with PYTHONPATH=../lib".format(name))
+ sys.exit(1)
+ else:
+ print("Cannot import {}".format(name))
+ sys.exit(1)
for sub in dir(module):
if sub[0] == '_':
continue
for kind in python_decl:
with os.popen('grep \'[[:blank:]]*auto{}::\' source/*rst|sed \'s/^.*auto{}:: //\''.format(kind, kind)) as pse:
for fullname in (l.strip() for l in pse):
- if not fullname in python_decl[kind]:
+ if fullname not in python_decl[kind]:
print("Warning: {} documented but declaration not found in python.".format(fullname))
else:
python_decl[kind].remove(fullname)
# Dump the missing ones
for kind in python_decl:
for fullname in python_decl[kind]:
- print("Missing decl: .. auto{}:: {}".format(kind, fullname))
+ print(" .. auto{}:: {}".format(kind, fullname))
################ And now deal with Doxygen declarations
################
doxy_funs = {} # {classname: {func_name: [args]} }
doxy_vars = {} # {classname: [names]}
+doxy_type = {} # {classname: [names]}
# find the declarations in the XML files
-for arg in xml_files[:1]:
+for arg in xml_files:
if arg[-4:] != '.xml':
print ("Argument '{}' does not end with '.xml'".format(arg))
continue
- print("Parse file {}".format(arg))
+ #print("Parse file {}".format(arg))
tree = ET.parse(arg)
for elem in tree.findall(".//compounddef"):
- if elem.attrib["prot"] != "public":
- continue
- if "compoundname" in elem:
- raise Exception("Compound {} has no 'compoundname' child tag.".format(elem))
- compoundname = elem.find("compoundname").text
- #print ("compoundname {}".format(compoundname))
+ if elem.attrib["kind"] == "class":
+ if elem.attrib["prot"] != "public":
+ continue
+ if "compoundname" in elem:
+ raise Exception("Compound {} has no 'compoundname' child tag.".format(elem))
+ compoundname = elem.find("compoundname").text
+ #print ("compoundname {}".format(compoundname))
+ elif elem.attrib["kind"] == "file":
+ compoundname = ""
+ elif elem.attrib["kind"] == "namespace":
+ compoundname = elem.find("compoundname").text
+ else:
+ print("Element {} is of kind {}".format(elem.attrib["id"], elem.attrib["kind"]))
+
for member in elem.findall('.//memberdef'):
if member.attrib["prot"] != "public":
continue
kind = member.attrib["kind"]
name = member.find("name").text
+ #print("kind:{} compoundname:{} name:{}".format( kind,compoundname, name))
if kind == "variable":
- if not compoundname in doxy_vars: doxy_vars[compoundname] = []
+ if compoundname not in doxy_vars:
+ doxy_vars[compoundname] = []
doxy_vars[compoundname].append(name)
elif kind == "function":
args = member.find('argsstring').text
args = re.sub('\)[^)]*$', ')', args) # ignore what's after the parameters (eg, '=0' or ' const')
- if not compoundname in doxy_funs: doxy_funs[compoundname] = {}
- if not name in doxy_funs[compoundname]: doxy_funs[compoundname][name] = []
+ if compoundname not in doxy_funs:
+ doxy_funs[compoundname] = {}
+ if name not in doxy_funs[compoundname]:
+ doxy_funs[compoundname][name] = []
doxy_funs[compoundname][name].append(args)
+ elif kind == "typedef":
+ if compoundname not in doxy_type:
+ doxy_type[compoundname] = []
+ doxy_type[compoundname].append(name)
+ elif kind == "friend":
+ pass # Ignore friendship
else:
print ("member {}::{} is of kind {}".format(compoundname, name, kind))
# Forget about the declarations that are done in the RST
-with os.popen('grep autodoxymethod:: source/*rst|sed \'s/^.*autodoxymethod:: //\'') as pse:
+with os.popen('grep doxygenfunction:: find-missing.ignore source/*rst|sed \'s/^.*doxygenfunction:: //\'') as pse:
for line in (l.strip() for l in pse):
(klass, obj, args) = (None, None, None)
if "(" in line:
(line, args) = line.split('(', 1)
args = "({}".format(args)
- (klass, obj) = line.rsplit('::', 1)
+ if '::' in line:
+ (klass, obj) = line.rsplit('::', 1)
+ else:
+ (klass, obj) = ("", line)
- if not klass in doxy_funs:
+ if klass not in doxy_funs:
print("Warning: {} documented, but class {} not found in doxygen.".format(line, klass))
continue
- if not obj in doxy_funs[klass]:
- print("Warning: Object {} documented but not found in {}".format(line, klass))
+ if obj not in doxy_funs[klass]:
+ print("Warning: Object '{}' documented but not found in '{}'".format(line, klass))
+# for obj in doxy_funs[klass]:
+# print(" found: {}::{}".format(klass, obj))
elif len(doxy_funs[klass][obj])==1:
del doxy_funs[klass][obj]
- elif not args in doxy_funs[klass][obj]:
+ elif args not in doxy_funs[klass][obj]:
print("Warning: Function {}{} not found in {}".format(obj, args, klass))
else:
-# print("Found {} in {}".format(line, klass))
+ #print("Found {} in {}".format(line, klass))
doxy_funs[klass][obj].remove(args)
if len(doxy_funs[klass][obj]) == 0:
del doxy_funs[klass][obj]
-with os.popen('grep autodoxyvar:: source/*rst|sed \'s/^.*autodoxyvar:: //\'') as pse:
+with os.popen('grep doxygenvariable:: find-missing.ignore source/*rst|sed \'s/^.*doxygenvariable:: //\'') as pse:
for line in (l.strip() for l in pse):
(klass, var) = line.rsplit('::', 1)
- if not klass in doxy_vars:
+ if klass not in doxy_vars:
print("Warning: {} documented, but class {} not found in doxygen.".format(line, klass))
continue
- if not var in doxy_vars[klass]:
- print("Warning: Object {} documented but not found in {}".format(line, klass))
+ if var not in doxy_vars[klass]:
+ print("Warning: Object {} documented but not found in '{}'".format(line, klass))
else:
# print("Found {} in {}".format(line, klass))
doxy_vars[klass].remove(var)
if len(doxy_vars[klass]) == 0:
del doxy_vars[klass]
+with os.popen('grep doxygentypedef:: find-missing.ignore source/*rst|sed \'s/^.*doxygentypedef:: //\'') as pse:
+ for line in (l.strip() for l in pse):
+ if '::' in line:
+ (klass, typ) = line.rsplit('::', 1)
+ else:
+ (klass, typ) = ('', line)
+
+ if klass not in doxy_type:
+ print("Warning: {} documented, but class {} not found in doxygen.".format(line, klass))
+ continue
+ if typ not in doxy_type[klass]:
+ print("Warning: Type {} documented but not found in '{}'".format(line, klass))
+ else:
+# print("Found {} in {}".format(line, klass))
+ doxy_type[klass].remove(typ)
+ if len(doxy_type[klass]) == 0:
+ del doxy_type[klass]
# Dump the undocumented Doxygen declarations
-for obj in doxy_funs:
- for meth in doxy_funs[obj]:
- for args in doxy_funs[obj][meth]:
- print("Missing decl: .. autodoxymethod:: {}::{}{}".format(obj, meth, args))
+for obj in sorted(doxy_funs):
+ for meth in sorted(doxy_funs[obj]):
+ for args in sorted(doxy_funs[obj][meth]):
+ if obj is '':
+ print(".. doxygenfunction:: {}{}".format(meth, args))
+ else:
+ print(".. doxygenfunction:: {}::{}{}".format(obj, meth, args))
for obj in doxy_vars:
- for meth in doxy_vars[obj]:
- print("Missing decl: .. autodoxyvar:: {}::{}".format(obj, meth))
+ for meth in sorted(doxy_vars[obj]):
+ print(".. doxygenvariable:: {}::{}".format(obj, meth))
+for obj in doxy_type:
+ for meth in sorted(doxy_type[obj]):
+ if obj is '':
+ print(".. doxygentypedef:: {}".format(meth))
+ else:
+ print(".. doxygentypedef:: {}::{}".format(obj, meth))
+
\ No newline at end of file
