Commits

Matt Clarkson committed 24314dc

Updated with Doxygen comments as we are using that internally now - figured may as well keep the open source in sync with hat we are doing internally

Comments (0)

Files changed (1)

gcov_to_clover.py

 #! /usr/bin/env python
 # encoding: utf-8
+
+##
+# @package udpwaflib.gcov_to_clover
+# @~english
+# A module that converts gcov output files into Atlassian clover XML files.
+#
+# It is open-sourced at:
+# https://bitbucket.org/atlassian/bamboo-gcov-plugin/
+#
+# @section gcov_to_clover_license License:
 #
 # Copyright (c) 2012, Matt Clarkson
 # All rights reserved.
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
-'''
-A module that converts gcov output files into Atlassian clover XML files.
-
-It is open-sourced at:
-https://bitbucket.org/atlassian/bamboo-gcov-plugin/
-'''
-
 import os
 import time
 from xml.dom import NotFoundErr
 import xml.dom.minidom as xmldom
 
+##
+# @~english
+# A class that can convert @c gcov output into a clover.xml for parsing by
+# Atlassian Bamboo
 class gcov_to_clover():
-    '''
-    Converts gcov output into a clover.xml for parsing by Atlassian Bamboo
-    '''
+    ##
+    # @~english
+    # The Clover XML document
     xml = xmldom.Document()
 
+    ##
+    # @~english
+    # Returns (or creates) an element with an attribute set to a value
+    # @param self the object pointer
+    # @param node the node to search under
+    # @param tag the tag to search for
+    # @param attribute the attribute to match
+    # @param value the attribute value to match
+    # @throws xml.dom.NotFoundError
+    # @returns an XML element
     def get_element(self, node, tag, attribute, value):
-        '''
-        Returns (or create) a tag with an attribute set to a value
-        :param node: the xml node to search from
-        :type node: Element
-        :param tag: the tag to find
-        :type tag: string
-        :param attribute: the attribute to match
-        :type attribute: string
-        :param value: the value to match
-        :type value: string
-        '''
         ret = None
         elements = node.getElementsByTagName(tag)
         for element in elements:
                 (tag, attribute, value))
         return ret
 
+    ##
+    # @~english
+    # Gets the Clover @c coverage node
+    # @param self the object pointer
+    # @returns the @c coverage node
     def get_coverage_node(self):
-        '''
-        Returns the coverage node
-        '''
         try:
             coverage_node = self.xml.getElementsByTagName('coverage')[0]
         except IndexError:
             self.xml.appendChild(coverage_node)
         return coverage_node
 
+    ##
+    # @~english
+    # Gets the Clover @c project node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @param project_prefix the prefix for the node name.  Mainly used in
+    #                       get_test_project_node
+    # @returns the @c project node
     def get_project_node(self, project_name, project_prefix = ''):
-        '''
-        Returns a project node
-        :param project_name: the project name to find
-        :type project_name: string
-        :param project_prefix: the prefix for the node name.  Mainly used in
-                               get_test_project_metrics_node
-        :type project_prefix: string
-        '''
         coverage_node = self.get_coverage_node()
         try:
             project_node = self.get_element(coverage_node, 'project', 'name',
             coverage_node.appendChild(project_node)
         return project_node
 
+    ##
+    # @~english
+    # Gets the Clover project @c metrics node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @param project_prefix the prefix for the node name.  Mainly used in
+    #                       get_test_project_metrics_node
+    # @returns the project @c metrics node
     def get_project_metrics_node(self, project_name, project_prefix = ''):
-        '''
-        Returns a project metrics node
-        :param project_name: the test project name to find
-        :type project_name: string
-        :param project_prefix: the prefix for the node name.  Mainly used in
-                               get_test_project_metrics_node
-        :type project_prefix: string
-        '''
         coverage_node = self.get_coverage_node()
         project_node = self.get_project_node(project_name, project_prefix)
         try:
             project_node.appendChild(project_metrics_node)
         return project_metrics_node
 
+    ##
+    # @~english
+    # Gets the Clover @c testproject node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @returns the @c testproject node
     def get_test_project_node(self, project_name):
         '''
         Returns a project metrics node
         '''
         return self.get_project_node(project_name, 'test')
 
+    ##
+    # @~english
+    # Gets the Clover test project @c metrics node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @returns the test project @c metrics node
     def get_test_project_metrics_node(self, project_name):
-        '''
-        Returns a project metrics node
-        :param project_name: the test project name to find
-        :type project_name: string
-        '''
         return self.get_project_metrics_node(project_name, 'test')
 
+    ##
+    # @~english
+    # Gets the Clover @c package node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @param package_name the package name to find
+    # @returns the @c package node
     def get_package_node(self, project_name, package_name):
-        '''
-        Returns a package node
-        :param project_name: the project that contains the package
-        :type project_name: string
-        :param package_name: the package name to find
-        :type package_name: string
-        '''
         project_node = self.get_project_node(project_name)
         try:
             package_node = self.get_element(project_node, 'package',
             project_node.appendChild(package_node)
         return package_node
 
+    ##
+    # @~english
+    # Gets the Clover test package @c metrics node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @param package_name the package name to find
+    # @returns the package @c metrics node
     def get_package_metrics_node(self, project_name, package_name):
-        '''
-        Returns a package metrics node
-        :param project_name: the project that contains the package
-        :type project_name: string
-        :param package_name: the package name to find
-        :type package_name: string
-        '''
         project_node = self.get_project_node(project_name)
         package_node = self.get_package_node(project_name, package_name)
         try:
             package_node.appendChild(package_metrics_node)
         return package_metrics_node
 
+    ##
+    # @~english
+    # Gets the Clover @c file node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @param package_name the package name to find
+    # @param file_path the file path to find
+    # @returns the @c file node
     def get_file_node(self, project_name, package_name, file_path):
         '''
         Returns a file node
             package_node.appendChild(file_node)
         return file_node
 
+    ##
+    # @~english
+    # Gets the Clover test file @c metrics node
+    # @param self the object pointer
+    # @param project_name the project name to find
+    # @param package_name the package name to find
+    # @param file_path the file path to find
+    # @returns the file @c metrics node
     def get_file_metrics_node(self, project_name, package_name,
         file_path):
-        '''
-        Returns a file metrics node
-        :param project_name: the project that contains the package
-        :type project_name: string
-        :param package_name: the package that contains the file
-        :type package_name: string
-        :param file_path: the file path to find
-        :type file_path: string
-        '''
         project_node = self.get_project_node(project_name)
         package_node = self.get_package_node(project_name, package_name)
         file_node = self.get_file_node(project_name, package_name,
             file_node.appendChild(file_metrics_node)
         return file_metrics_node
 
+    ##
+    # @~english
+    # Sets the class metrics attributes on a Clover XML node
+    # @param self the object pointer
+    # @param xml_node the node to set the attributes on
+    # @returns None
     def set_class_metric_attributes(self, xml_node):
-        '''
-        Set the class metric attributes on a node
-        :param xml_node: the XML element to set the attributes on
-        :type xml_node: xml.dom.Node
-        '''
         xml_node.setAttribute('complexity', '0')
         xml_node.setAttribute('elements', '0')
         xml_node.setAttribute('coveredelements', '0')
         xml_node.setAttribute('testpasses', '0')
         xml_node.setAttribute('testruns', '0')
 
+    ##
+    # @~english
+    # Sets the file metrics attributes on a Clover XML node
+    # @param self the object pointer
+    # @param xml_node the node to set the attributes on
+    # @returns None
     def set_file_metric_attributes(self, xml_node):
-        '''
-        Set the file metric attributes on a node
-        :param xml_node: the XML element to set the attributes on
-        :type xml_node: xml.dom.Node
-        '''
         self.set_class_metric_attributes(xml_node)
         xml_node.setAttribute('classes', '0')
         xml_node.setAttribute('loc', '0')
         xml_node.setAttribute('ncloc', '0')
 
+    ##
+    # @~english
+    # Sets the package metrics attributes on a Clover XML node
+    # @param self the object pointer
+    # @param xml_node the node to set the attributes on
+    # @returns None
     def set_package_metric_attributes(self, xml_node):
         '''
         Set the package metric attributes on a node
         self.set_file_metric_attributes(xml_node)
         xml_node.setAttribute('files', '0')
 
+    ##
+    # @~english
+    # Sets the project metrics attributes on a Clover XML node
+    # @param self the object pointer
+    # @param xml_node the node to set the attributes on
+    # @returns None
     def set_project_metric_attributes(self, xml_node):
         '''
         Set the project metric attributes on a node
         self.set_package_metric_attributes(xml_node)
         xml_node.setAttribute('packages', '0')
 
+    ##
+    # @~english
+    # Sets the project metrics attributes on a Clover XML node
+    # @param self the object pointer
+    # @param file_path the gcov output file path
+    # @param project_name the project this file belongs to
+    # @param package_name the package this file belongs to
+    # @returns None
     def parse_file(self, file_path,
             project_name = "Unknown",
             package_name = "Unknown"):
-        '''
-        Parses a gcov file
-        :param file_path: the gcov output absolute file path
-        :type file_path: string
-        :param project_name: the project this file belongs to (default: "Unknown")
-        :type project_name: string
-        :param package_name: the package this file belongs to (default: "Unknown")
-        :type package_name: string
-        '''
         file_path = os.path.normpath(os.path.abspath(file_path))
 
         # Get the nodes we need for this file
         project_metrics_node.setAttribute('packages',
             str(len(project_node.getElementsByTagName('package'))))
 
+    ##
+    # @~english
+    # Writes the clover file to disk
+    # @param self the object pointer
+    # @param output_path the filesystem path to write the XML file to
+    # @param indent the indentation characters to put into the XML
+    # @param new_line the new line characters to put into the XML
+    # @returns None
     def write(self, output_path, indent = '  ', new_line = '\n'):
-        '''
-        Writes the clover file to disk
-        :param output_path: the filesystem path to write the XML file too
-        :type output_path: string
-        :param indent: the indentation characters to put into the XML
-        :type indent: string
-        :param new_line: the new line characters to put into the XML
-        :type new_line: string
-        '''
         addindent = '  '
         with open(output_path, 'w') as f:
             self.xml.writexml(f,
                 addindent = indent, newl = new_line, encoding= 'UTF-8')
         self.xml.unlink()
 
+    ##
+    # @~english
+    # Parses a list of @c gcov output file paths
+    # @param self the object pointer
+    # @param file_paths a list of filesystem paths
+    # @returns None
     def parse(self, file_paths):
-        '''
-        Parses a list of absolute file paths
-        :param file_paths: a list of filesystem absolute paths
-        :type file_paths: list of strings
-        '''
         if not isinstance(file_paths, list):
             file_paths = [file_paths]
         for file_path in file_paths:
             self.parse_file(file_path)
 
-    def process(self, files, output_path):
-        '''
-        Threads execute this function
-        '''
-        self.parse(files)
+    ##
+    # @~english
+    # Processes list of @c gcov output filesystem paths and writes a Clover XML
+    # file
+    # @param self the object pointer
+    # @param file_paths a list of filesystem paths
+    # @param output_path the filesystem path to write the XML file to
+    # @returns None
+    def process(self, file_paths, output_path):
+        self.parse(file_paths)
         self.write(output_path)
 
+## @cond internal
+
 # Executable stuff
 if __name__ == '__main__':
     import argparse
     import sys
 
+    ##
+    # @~english
+    # The main function if we are executing this as a standalone file
     def main():
         parser = argparse.ArgumentParser(description = __doc__,
             epilog = 'example: %s example.cpp.gcov' % sys.argv[0])
         gtc.process(args.file_paths, args.output)
 
     main()
+
+## @endcond