Skip to content

Commit

Permalink
Doxygen test also checks for broken 'see also' links
Browse files Browse the repository at this point in the history
  • Loading branch information
nyalldawson committed May 25, 2018
1 parent 1d8689f commit fa912f5
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 2 deletions.
31 changes: 29 additions & 2 deletions tests/code_layout/doxygen_parser.py
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ def __init__(self, path, acceptable_missing={}, acceptable_missing_added_note=[]
self.documented_members = 0
self.undocumented_members = {}
self.noncompliant_members = {}
self.broken_links = {}
self.bindable_members = []
self.groups = {}
self.classes_missing_group = []
Expand Down Expand Up @@ -141,7 +142,7 @@ def parseFile(self, f):
if event == 'end' and elem.tag == 'compounddef':
if self.elemIsPublicClass(elem):
# store documentation status
members, documented, undocumented, noncompliant, bindable, has_brief_description, found_version_added = self.parseClassElem(elem)
members, documented, undocumented, noncompliant, bindable, has_brief_description, found_version_added, broken_links = self.parseClassElem(elem)
documentable_members += members
documented_members += documented
class_name = elem.find('compoundname').text
Expand Down Expand Up @@ -172,6 +173,9 @@ def parseFile(self, f):
if len(noncompliant) > 0:
self.noncompliant_members[class_name] = noncompliant

if broken_links:
self.broken_links[class_name] = broken_links

# store bindable members
if self.classElemIsBindable(elem):
for m in bindable:
Expand Down Expand Up @@ -230,6 +234,7 @@ def parseClassElem(self, e):
undocumented_members = set()
noncompliant_members = []
bindable_members = []
broken_links = {}
# loop through all members
for m in e.getiterator('memberdef'):
signature = self.memberSignature(m)
Expand All @@ -248,6 +253,11 @@ def parseClassElem(self, e):
noncompliant_members.append({m.find('name').text: error})
else:
undocumented_members.add(signature)

broken_see_also_links = self.checkForBrokenSeeAlsoLinks(m)
if broken_see_also_links:
broken_links[m.find('name').text] = broken_see_also_links

# test for brief description
d = e.find('briefdescription')
has_brief_description = False
Expand All @@ -267,7 +277,7 @@ def parseClassElem(self, e):
if found_version_added:
break

return documentable_members, documented_members, undocumented_members, noncompliant_members, bindable_members, has_brief_description, found_version_added
return documentable_members, documented_members, undocumented_members, noncompliant_members, bindable_members, has_brief_description, found_version_added, broken_links

def memberSignature(self, elem):
""" Returns the signature for a member
Expand Down Expand Up @@ -565,3 +575,20 @@ def memberDocIsNonCompliant(self, member_elem):
#elif para.text.strip().lower().startswith('set '):
# return 'Use "Sets the..." instead of "set ..."'
return False

def checkForBrokenSeeAlsoLinks(self, elem):
"""
Checks for any broken 'see also' links
"""
broken = []
detailed_sec = elem.find('detaileddescription')
for p in detailed_sec.getiterator('para'):
for s in p.getiterator('simplesect'):
if s.get('kind') != 'see':
continue

para = s.getchildren()[0]
if para.find('ref') is None and para.text:
broken.append(para.text)

return broken
6 changes: 6 additions & 0 deletions tests/code_layout/test_qgsdoccoverage.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,12 @@ def testCoverage(self):
for mem, error in p.items():
print((colored(' ' + mem + ': ' + error, 'yellow', attrs=['bold'])))

if parser.broken_links:
for cls, props in list(parser.broken_links.items()):
print(('\n\nClass {}, broken see also links found\n'.format(colored(cls, 'yellow'))))
for member, links in props.items():
for l in links:
print((colored(' ' + member + ': ' + l, 'yellow', attrs=['bold'])))
# self.assertEquals(len(parser.undocumented_string), 0, 'FAIL: new undocumented members have been introduced, please add documentation for these members')

if parser.classes_missing_group:
Expand Down

0 comments on commit fa912f5

Please sign in to comment.