Merge pull request #7054 from nyalldawson/compliant

Add compliance test to doxygen test

python/gui/auto_generated/editorwidgets/core/qgseditorwidgetwrapper.sip.in

@@ -187,16 +187,17 @@ Add a hint text on the widget
 
     ConstraintResult constraintResult() const;
 %Docstring
-Getter of constraintResult
-It's the current result of the constraint on the widget influencing it's visualization.
+Returns the constraint result, which is the current result of the constraint
+on the widget influencing its visualization.
 
 .. versionadded:: 3.0
 %End
 
     bool constraintResultVisible() const;
 %Docstring
-Getter of constraintResultVisible
-Defines if the constraint result should be visualized on the widget (with color).
+Returns whether the constraint result is visible.
+
+Returns true if the constraint result will be visualized on the widget (with color).
 This will be disabled when the form is not editable.
 
 .. versionadded:: 3.0
@@ -204,8 +205,9 @@ This will be disabled when the form is not editable.
 
     void setConstraintResultVisible( bool constraintResultVisible );
 %Docstring
-Setter of constraintResultVisible
-Defines if the constraint result should be visualized on the widget (with color).
+Sets whether the constraint result is visible.
+
+Controls if the constraint result should be visualized on the widget (with color).
 This will be disabled when the form is not editable.
 
 :param constraintResultVisible: if constraintResult should be displayed (mostly editable status)
@@ -213,7 +215,6 @@ This will be disabled when the form is not editable.
 .. versionadded:: 3.0
 %End
 
-
   signals:
 
     void valueChanged( const QVariant &value );

python/gui/auto_generated/qgsattributetypeloaddialog.sip.in

@@ -35,7 +35,7 @@ Sets predefined vector layer for selection of data
 
     QMap<QString, QVariant> &valueMap();
 %Docstring
-Getter to value map which is currently active
+Returns the value map which is currently active.
 
 :return: value map of vlues selected from layer
 %End

src/gui/editorwidgets/core/qgseditorwidgetwrapper.h

@@ -190,30 +190,34 @@ class GUI_EXPORT QgsEditorWidgetWrapper : public QgsWidgetWrapper
     virtual void setHint( const QString &hintText );
 
     /**
-     * Getter of constraintResult
-     * It's the current result of the constraint on the widget influencing it's visualization.
+     * Returns the constraint result, which is the current result of the constraint
+     * on the widget influencing its visualization.
+     *
      * \since QGIS 3.0
      */
     ConstraintResult constraintResult() const;
 
     /**
-     * Getter of constraintResultVisible
-     * Defines if the constraint result should be visualized on the widget (with color).
+     * Returns whether the constraint result is visible.
+     *
+     * Returns true if the constraint result will be visualized on the widget (with color).
      * This will be disabled when the form is not editable.
+     *
      * \since QGIS 3.0
      */
     bool constraintResultVisible() const;
 
     /**
-     * Setter of constraintResultVisible
-     * Defines if the constraint result should be visualized on the widget (with color).
+     * Sets whether the constraint result is visible.
+     *
+     * Controls if the constraint result should be visualized on the widget (with color).
      * This will be disabled when the form is not editable.
+     *
      * \param constraintResultVisible if constraintResult should be displayed (mostly editable status)
      * \since QGIS 3.0
      */
     void setConstraintResultVisible( bool constraintResultVisible );
 
-
   signals:
 
     /**

src/gui/qgsattributetypeloaddialog.h

@@ -52,7 +52,8 @@ class GUI_EXPORT QgsAttributeTypeLoadDialog: public QDialog, private Ui::QgsAttr
     void setVectorLayer( QgsVectorLayer *layer );
 
     /**
-     * Getter to value map which is currently active
+     * Returns the value map which is currently active.
+     *
      * \returns value map of vlues selected from layer
      */
     QMap<QString, QVariant> &valueMap();

tests/code_layout/doxygen_parser.py

@@ -52,6 +52,7 @@ class DoxygenParser():
         self.documentable_members = 0
         self.documented_members = 0
         self.undocumented_members = {}
+        self.noncompliant_members = {}
         self.bindable_members = []
         self.groups = {}
         self.classes_missing_group = []
@@ -140,7 +141,7 @@ class DoxygenParser():
                 if event == 'end' and elem.tag == 'compounddef':
                     if self.elemIsPublicClass(elem):
                         # store documentation status
-                        members, documented, undocumented, bindable, has_brief_description, found_version_added = self.parseClassElem(elem)
+                        members, documented, undocumented, noncompliant, bindable, has_brief_description, found_version_added = self.parseClassElem(elem)
                         documentable_members += members
                         documented_members += documented
                         class_name = elem.find('compoundname').text
@@ -168,6 +169,9 @@ class DoxygenParser():
                             self.undocumented_members[class_name]['members'] = members
                             self.undocumented_members[class_name]['missing_members'] = unacceptable_undocumented
 
+                        if len(noncompliant) > 0:
+                            self.noncompliant_members[class_name] = noncompliant
+
                         # store bindable members
                         if self.classElemIsBindable(elem):
                             for m in bindable:
@@ -224,6 +228,7 @@ class DoxygenParser():
         documentable_members = 0
         documented_members = 0
         undocumented_members = set()
+        noncompliant_members = []
         bindable_members = []
         # loop through all members
         for m in e.getiterator('memberdef'):
@@ -238,6 +243,9 @@ class DoxygenParser():
                 documentable_members += 1
                 if self.memberIsDocumented(m):
                     documented_members += 1
+                    error = self.memberDocIsNonCompliant(m)
+                    if error:
+                        noncompliant_members.append({m.find('name').text: error})
                 else:
                     undocumented_members.add(signature)
         # test for brief description
@@ -259,7 +267,7 @@ class DoxygenParser():
             if found_version_added:
                 break
 
-        return documentable_members, documented_members, undocumented_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
 
     def memberSignature(self, elem):
         """ Returns the signature for a member
@@ -537,3 +545,23 @@ class DoxygenParser():
             if doc is not None and list(doc):
                 return True
         return False
+
+    def memberDocIsNonCompliant(self, member_elem):
+        """ Tests whether an member's documentation is non-compliant
+            :param member_elem: XML element for a class member
+        """
+        for doc_type in ['briefdescription']:
+            doc = member_elem.find(doc_type)
+            if doc is not None:
+                for para in doc.getiterator('para'):
+                    if not para.text:
+                        continue
+                    if para.text.strip().lower().startswith('getter'):
+                        return 'Use "Returns the..." instead of "getter"'
+                    elif para.text.strip().lower().startswith('setter'):
+                        return 'Use "Sets the..." instead of "setter"'
+                    #elif para.text.strip().lower().startswith('return '):
+                    #    return 'Use "Returns the..." instead of "return ..."'
+                    #elif para.text.strip().lower().startswith('set '):
+                    #    return 'Use "Sets the..." instead of "set ..."'
+        return False

tests/code_layout/test_qgsdoccoverage.py

@@ -60,6 +60,13 @@ class TestQgsDocCoverage(unittest.TestCase):
                 for mem in props['missing_members']:
                     print((colored('  "' + mem + '"', 'yellow', attrs=['bold'])))
 
+        if parser.noncompliant_members:
+            for cls, props in list(parser.noncompliant_members.items()):
+                print(('\n\nClass {}, non-compliant members found\n'.format(colored(cls, 'yellow'))))
+                for p in props:
+                    for mem, error in p.items():
+                        print((colored('  ' + mem + ': ' + error, '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:
@@ -88,6 +95,7 @@ class TestQgsDocCoverage(unittest.TestCase):
         self.assertTrue(not parser.classes_missing_group, 'Classes without \\group tag found')
         self.assertTrue(not parser.classes_missing_version_added, 'Classes without \\since version tag found')
         self.assertTrue(not parser.classes_missing_brief, 'Classes without \\brief description found')
+        self.assertTrue(not parser.noncompliant_members, 'Non compliant members found')
 
 
 if __name__ == '__main__':