diff --git a/tests/src/python/acceptable_missing_doc.py b/tests/src/python/acceptable_missing_doc.py index 9b4077fd175b..2c5e0b28d5af 100644 --- a/tests/src/python/acceptable_missing_doc.py +++ b/tests/src/python/acceptable_missing_doc.py @@ -1578,3 +1578,284 @@ "QgsActionMenu", "QgsAuthMethod", "QgsDartMeasurement"] + +ACCEPTABLE_MISSING_BRIEF = ['QgsBrushStyleComboBox', + 'QgsHiddenWidgetFactory', + 'QgsLabelCandidate', + 'QgsIDWInterpolator', + 'QgsFeatureSelectionModel', + 'QgsColorWidgetFactory', + 'QgsFieldValidator', + 'QgsPointCompare', + 'QgsSvgSelectorWidget', + 'QgsGeometryGeneratorSymbolLayerV2', + 'QgsSurfaceV2', + 'QgsSvgAnnotationItem', + 'QgsCptCityColorRampV2Dialog', + 'QgsRangeConfigDlg', + 'QgsAttributeFormInterface', + 'QgsExpression::NodeUnaryOperator', + 'QgsSymbolLayerV2Widget', + 'pal::PriorityQueue', + 'QgsVectorLayerEditUtils', + 'QgsArcProperter', + 'QgsSimpleMarkerSymbolLayerV2Widget', + 'QgsBrowserWatcher', + 'QgsRandomColorsV2', + 'QgsVectorLayerEditPassthrough', + 'QgsDial', + 'QgsVectorColorBrewerColorRampV2Dialog', + 'QgsFontMarkerSymbolLayerV2Widget', + 'QgsSymbolV2LevelItem', + 'QgsGroupBoxCollapseButton', + 'QgsVectorFieldSymbolLayerWidget', + 'QgsCentroidFillSymbolLayerV2Widget', + 'QgsEnumerationWidgetWrapper', + 'QgsError', + 'QgsRendererRangeV2LabelFormat', + 'QgsMimeDataUtils', + 'QgsRangeWidgetFactory', + 'QgsCptCityArchive', + 'QgsRasterRendererWidget', + 'QgsGmlSchema', + 'HalfEdge', + 'QgsDateTimeEditFactory', + 'QgsVectorFileWriter::BoolOption', + 'QgsRasterFillSymbolLayerWidget', + 'QgsVectorRandomColorRampV2Dialog', + 'QgsSymbolV2RenderContext', + 'QgsErrorDialog', + 'QgsExpressionHighlighter', + 'QgsFileNameWidgetFactory', + 'QgsExpression::NodeLiteral', + 'pal::CostCalculator', + 'QgsFillSymbolLayerV2', + 'QgsMultiBandColorRendererWidget', + 'QgsRuleBasedLabeling::Rule', + 'QgsSpatialIndexCopyVisitor', + 'QgsSVGFillSymbolLayerWidget', + 'QgsDataDefinedWidthDialog', + 'QgsShapeburstFillSymbolLayerV2', + 'QgsLegacyHelpers', + 'QgsLineSymbolLayerV2', + 'QgsWkbPtr', + 'QgsSymbolLayerV2', + 'QgsVectorFileWriter::StringOption', + 'QgsSymbolLevelsV2Dialog', + 'QgsPenJoinStyleComboBox', + 'QgsValueRelationWidgetFactory', + 'QgsGlowWidget', + 'QgsDummyConfigDlg', + 'QgsExpression::NodeFunction', + 'QgsSvgSelectorGroupsModel', + 'QgsAttributeTypeLoadDialog', + 'QgsDirectoryParamWidget', + 'QgsCategorizedSymbolRendererV2', + 'QgsQtLocationConnection', + 'QgsPropertyKey', + 'QgsRuntimeProfiler', + 'QgsVectorFileWriter::Option', + 'QgsSymbolV2', + 'QgsRendererRangeV2', + 'QgsRasterCalcNode', + 'QgsMessageBarItem', + 'QgsVectorFileWriter::SetOption', + 'QgsCacheIndexFeatureId', + 'QgsRasterProjector', + 'QgsPropertyValue', + 'QgsAttributeTableFilterModel', + 'QgsSingleSymbolRendererV2Widget', + 'QgsValueMapConfigDlg', + 'QgsSmartGroupCondition', + 'QgsMarkerLineSymbolLayerV2Widget', + 'QgsExpression::NodeList', + 'QgsSymbolV2SelectorDialog', + 'QgsPalLayerSettings', + 'QgsTextEditConfigDlg', + 'QgsWkbException', + 'QgsSingleBandPseudoColorRendererWidget', + 'QgsRuleBasedLabeling', + 'QgsDxfExport', + 'pal::GeomFunction', + 'QgsRasterLayerSaveAsDialog', + 'QgsStyleV2', + 'QgsSizeScaleWidget', + 'QgsSymbolsListWidget', + 'QgsFontMarkerSymbolLayerV2', + 'QgsLUDialog', + 'QgsLegendInterface', + 'QgsSublayersDialog', + 'QgsDrawSourceWidget', + 'QgsSingleBandGrayRendererWidget', + 'QgsRelationEditorWidget', + 'QgsFeatureSelectionDlg', + 'QgsDataDefinedRotationDialog', + 'QgsRendererV2PropertiesDialog', + 'QgsDistanceArcProperter', + 'QgsComposerLayerItem', + 'QgsRelationReferenceFactory', + 'QgsLongLongValidator', + 'QgsExpression::WhenThen', + 'QgsVectorFileWriter::IntOption', + 'QgsUniqueValueWidgetFactory', + 'QgsRelationReferenceWidget', + 'QgsSLConnect', + 'pal::LabelPosition', + 'Node', + 'QgsRendererRulePropsDialog', + 'Qgs25DRendererWidget', + 'QgsPalLabeling', + 'QgsTextDiagram', + 'QgsMapToolCapture', + 'QgsConstWkbSimplifierPtr', + 'QgsTextEditWidgetFactory', + 'QgsNewVectorLayerDialog', + 'QgsLogger', + 'CharacterWidget', + 'QgsPointDisplacementRendererWidget', + 'QgsProjectFileTransform', + 'QgsExpression::NodeInOperator', + 'QgsLocaleNumC', + 'QgsDatumTransformDialog', + 'QgsColorRampComboBox', + 'QgsGeometryValidator', + 'QgsValueRelationConfigDlg', + 'QgsComposerSymbolV2Item', + 'QgsScaleRangeWidget', + 'QgsPieDiagram', + 'QgsVectorGradientColorRampV2Dialog', + 'QgsPluginManagerInterface', + 'QgsAttributeTableMapLayerAction', + 'QgsConstWkbPtr', + 'QgsStyleV2ExportImportDialog', + 'QgsBrowserModel', + 'QgsUniqueValuesConfigDlg', + 'QgsStyleV2GroupSelectionDialog', + 'QgsScaleVisibilityDialog', + 'QgsSpatialIndex', + 'QgsFeatureModel', + 'QgsSvgMarkerSymbolLayerV2Widget', + 'QgsFeatureListModel', + 'QgsDataDefinedSizeDialog', + 'QgsColorEffectWidget', + 'QgsComposerStyleItem', + 'QgsWebPage', + 'QgsRelationReferenceConfigDlg', + 'QgsVectorLayerEditBuffer', + 'QgsGraduatedSymbolRendererV2Widget', + 'QgsSimpleLineSymbolLayerV2', + 'QgsSingleSymbolRendererV2', + 'QgsComposerHtml', + 'QgisInterface', + 'QgsRuleBasedLabelProvider', + 'QgsPointPatternFillSymbolLayer', + 'QgsGradientFillSymbolLayerV2', + 'QgsLinearlyInterpolatedDiagramRenderer', + 'QgsWebViewWidgetConfigDlg', + 'QgsGradientFillSymbolLayerV2Widget', + 'QgsSlider', + 'QgsPointPatternFillSymbolLayerWidget', + 'QgsAttributeForm', + 'pal::Sol', + 'QgsCptCityColorRampV2', + 'QgsComposerMultiFrameCommand', + 'QgsSimpleLineSymbolLayerV2Widget', + 'QgsValueMapWidgetFactory', + 'QgsRelation', + 'QgsInvertedPolygonRenderer', + 'QgsExpression::Node', + 'QgsTransformWidget', + 'QgsGroupWMSDataDialog', + 'QgsDataDefinedSymbolDialog', + 'QgsColorBrewerPalette', + 'LinTriangleInterpolator', + 'QgsFontUtils', + 'QgsDxfPaintEngine', + 'QgsPenStyleComboBox', + 'QgsRendererRulePropsWidget', + 'QgsSimpleFillSymbolLayerV2', + 'QgsExpression::NodeCondition', + 'QgsClassificationWidgetWrapperFactory', + 'QgsClassificationWidgetWrapper', + 'QgsPhotoConfigDlg', + 'QgsErrorMessage', + 'QgsRelationWidgetWrapper', + 'Qgs25DRenderer', + 'QgsTrackedVectorLayerTools', + 'QgsSymbolLayerV2Utils', + 'QgsComposerRasterSymbolItem', + 'Point3D', + 'QgsGeometryGeneratorSymbolLayerWidget', + 'QgsVectorLayerFeatureIterator', + 'QgsFeatureRendererV2', + 'QgsRasterMinMaxWidget', + 'QgsDateTimeEditConfig', + 'QgsSvgCacheEntry', + 'QgsShapeburstFillSymbolLayerV2Widget', + 'QgsMapLayerConfigWidgetFactory', + 'QgsManageConnectionsDialog', + 'QgsSvgSelectorListModel', + 'QgsMarkerLineSymbolLayerV2', + 'QgsScopeLogger', + 'QgsExpression::NodeColumnRef', + 'QgsCheckBoxConfigDlg', + 'QgsDockWidget', + 'QgsUuidWidgetFactory', + 'QgsFeatureListViewDelegate', + 'QgsOfflineEditing', + 'QgsLabelPosition', + 'QgsEnumerationWidgetFactory', + 'QgsLinePatternFillSymbolLayerWidget', + 'QgsSvgSelectorDialog', + 'QgsGeometryCache', + 'QgsRuleBasedRendererV2Widget', + 'QgsScaleUtils', + 'QgsMarkerSymbolV2', + 'QgsPalettedRendererWidget', + 'QgsPenCapStyleComboBox', + 'QgsVectorFileWriter::HiddenOption', + 'QgsExternalResourceWidgetFactory', + 'QgsComposerGroupItem', + 'QgsAttributeTableAction', + 'QgsEditFormConfig', + 'QgsCategorizedSymbolRendererV2Widget', + 'QgsNewMemoryLayerDialog', + 'QgsEllipseSymbolLayerV2Widget', + 'QgsExpression::NodeBinaryOperator', + 'QgsCentroidFillSymbolLayerV2', + 'DualEdgeTriangulation', + 'QgsLineSymbolV2', + 'QgsHillshadeFilter', + 'QgsServerInterface', + 'QgsLayerPropertiesWidget', + 'QgsLinePatternFillSymbolLayer', + 'QgsWebViewWidgetFactory', + 'QgsAttributeDialog', + 'QgsGeometry::Error', + 'QgsRasterMatrix', + 'QgsPhotoWidgetFactory', + 'QgsComposerEffect', + 'QgsArrowSymbolLayerWidget', + 'QgsFillSymbolV2', + 'QgsVectorLayerSelectionManager', + 'pal::PointSet', + 'QgsSimpleFillSymbolLayerV2Widget', + 'ParametricLine', + 'QgsGraduatedSymbolRendererV2', + 'QgsExternalResourceConfigDlg', + 'QgsHistogramDiagram', + 'QgsBlurWidget', + 'QgsShadowEffectWidget', + 'QgsRendererRasterPropertiesWidget', + 'QgsVectorColorBrewerColorRampV2', + 'QgsTransactionGroup', + 'pal::Util', + 'QgsDartMeasurement', + 'QgsSvgMarkerSymbolLayerV2', + 'QgsAlignRaster', + 'QgsCheckboxWidgetFactory', + 'QgsAddRemoveMultiFrameCommand', + 'QgsCptCityBrowserModel', + 'QgsSmartGroupEditorDialog', + 'QgsHeatmapRendererWidget', + 'QgsStyleV2ManagerDialog'] diff --git a/tests/src/python/test_qgsdoccoverage.py b/tests/src/python/test_qgsdoccoverage.py index 88c67790b5d2..2e4e046809e3 100644 --- a/tests/src/python/test_qgsdoccoverage.py +++ b/tests/src/python/test_qgsdoccoverage.py @@ -16,7 +16,7 @@ from qgis.testing import unittest from utilities import printImportant, DoxygenParser -from acceptable_missing_doc import ACCEPTABLE_MISSING_DOCS, ACCEPTABLE_MISSING_ADDED_NOTE +from acceptable_missing_doc import ACCEPTABLE_MISSING_DOCS, ACCEPTABLE_MISSING_ADDED_NOTE, ACCEPTABLE_MISSING_BRIEF # TO regenerate the list: # uncomment the lines under the `# GEN LIST` @@ -34,7 +34,7 @@ def testCoverage(self): print('CTEST_FULL_OUTPUT') prefixPath = os.environ['QGIS_PREFIX_PATH'] docPath = os.path.join(prefixPath, '..', 'doc', 'api', 'xml') - parser = DoxygenParser(docPath, ACCEPTABLE_MISSING_DOCS, ACCEPTABLE_MISSING_ADDED_NOTE) + parser = DoxygenParser(docPath, ACCEPTABLE_MISSING_DOCS, ACCEPTABLE_MISSING_ADDED_NOTE, ACCEPTABLE_MISSING_BRIEF) coverage = 100.0 * parser.documented_members / parser.documentable_members missing = parser.documentable_members - parser.documented_members @@ -55,6 +55,8 @@ def testCoverage(self): self.assertTrue(len(parser.classes_missing_version_added) == 0, 'FAIL: {} classes have been added without a version added doxygen note ("@note added in QGIS x.xx"):\n{}'.format(len(parser.classes_missing_version_added), '\n'.join(parser.classes_missing_version_added))) + self.assertTrue(len(parser.classes_missing_brief) == 0, 'FAIL: {} classes have been added without a brief description:\n{}'.format(len(parser.classes_missing_brief), '\n'.join(parser.classes_missing_brief))) + if __name__ == '__main__': unittest.main() diff --git a/tests/src/python/utilities.py b/tests/src/python/utilities.py index c95026507193..5577881010d8 100644 --- a/tests/src/python/utilities.py +++ b/tests/src/python/utilities.py @@ -349,19 +349,21 @@ class DoxygenParser(): Parses the XML files generated by Doxygen which describe the API docs """ - def __init__(self, path, acceptable_missing={}, acceptable_missing_added_note=[]): + def __init__(self, path, acceptable_missing={}, acceptable_missing_added_note=[], acceptable_missing_brief=[]): """ Initializes the parser. :param path: Path to Doxygen XML output """ self.acceptable_missing = acceptable_missing self.acceptable_missing_added_note = acceptable_missing_added_note + self.acceptable_missing_brief = acceptable_missing_brief self.documentable_members = 0 self.documented_members = 0 self.undocumented_string = '' self.bindable_members = [] self.groups = {} self.classes_missing_group = [] + self.classes_missing_brief = [] self.classes_missing_version_added = [] # for some reason the Doxygen generation on Travis refuses to assign these classes to groups self.acceptable_missing_group = ['QgsOgcUtils::LayerProperties', @@ -432,7 +434,7 @@ def parseFile(self, f): if event == 'end' and elem.tag == 'compounddef': if self.elemIsPublicClass(elem): # store documentation status - members, documented, undocumented, bindable, found_version_added = self.parseClassElem(elem) + members, documented, undocumented, bindable, has_brief_description, found_version_added = self.parseClassElem(elem) documentable_members += members documented_members += documented class_name = elem.find('compoundname').text @@ -440,6 +442,8 @@ def parseFile(self, f): if not self.hasGroup(class_name) and not class_name in self.acceptable_missing_group: self.classes_missing_group.append(class_name) + if not class_name in self.acceptable_missing_brief and not has_brief_description: + self.classes_missing_brief.append(class_name) if not class_name in self.acceptable_missing_added_note and not found_version_added: self.classes_missing_version_added.append(class_name) @@ -527,6 +531,14 @@ def parseClassElem(self, e): documented_members += 1 else: undocumented_members.add(signature) + # test for brief description + d = e.find('briefdescription') + has_brief_description = False + if d: + p = d.find('para') + if p.text and len(p.text) > 0: + has_brief_description = True + # test for "added in QGIS xxx" string d = e.find('detaileddescription') found_version_added = False @@ -537,7 +549,7 @@ def parseClassElem(self, e): if p.text and p.text.lower().startswith('added in'): found_version_added = True - return documentable_members, documented_members, undocumented_members, bindable_members, found_version_added + return documentable_members, documented_members, undocumented_members, bindable_members, has_brief_description, found_version_added def memberSignature(self, elem): """ Returns the signature for a member