Added ivar documentation for Statistics, ExecutionErrors and Message

asyrjasalo · asyrjasalo · commit 370c88674a15 · 2013-06-10T17:17:04.000+03:00
Update issue 1468

Added documentation for Statistics, ExecutionErrors and Message internal variables.
diff --git a/src/robot/model/message.py b/src/robot/model/message.py
@@ -19,6 +19,18 @@
 
 
 class Message(ModelObject):
+    """A message outputted during the test execution.
+
+    The message can be a log message triggered by a keyword, or a warning
+    or an error occurred during the test execution.
+
+    :ivar message: The message content as a string.
+    :ivar level: Severity of the message. Either ``TRACE``, ``INFO``,
+                 ``WARN``, ``DEBUG`` or ``FAIL``/``ERROR``.
+    :ivar html: ``True`` if the content is in HTML, ``False`` otherwise.
+    :ivar timestamp: Timestamp in format ``%Y%m%d %H:%M:%S.%f``.
+    :ivar parent: The object this message was triggered by.
+    """
     __slots__ = ['message', 'level', 'html', 'timestamp', 'parent']
 
     def __init__(self, message='', level='INFO', html=False, timestamp=None,
@@ -31,6 +43,8 @@ def __init__(self, message='', level='INFO', html=False, timestamp=None,
 
     @property
     def html_message(self):
+        """Returns the message content as HTML.
+        """
         return self.message if self.html else html_escape(self.message)
 
     def visit(self, visitor):
diff --git a/src/robot/model/statistics.py b/src/robot/model/statistics.py
@@ -19,6 +19,15 @@
 
 
 class Statistics(object):
+    """Container for total, suite and tag statistics.
+
+    Accepted parameters have the same semantics as the matching command line
+    options.
+
+    :ivar total: Instance of :class:`~robot.model.totalstatistics.TotalStatistics`.
+    :ivar suite: Instance of :class:`~robot.model.suitestatistics.SuiteStatistics`.
+    :ivar tags: Instance of :class:`~robot.model.tagstatistics.TagStatistics`.
+    """
 
     def __init__(self, suite, suite_stat_level=-1, tag_stat_include=None,
                  tag_stat_exclude=None, tag_stat_combine=None, tag_doc=None,
diff --git a/src/robot/model/stats.py b/src/robot/model/stats.py
@@ -18,6 +18,19 @@
 
 
 class Stat(object):
+    """Generic statistic object used for storing all the statistic values.
+
+    :ivar name: Human readable identifier of the object these statistics
+                belong to. Either `All Tests` or `Critical Tests` for
+                :class:`~robot.model.totalstatistics.TotalStatistics`,
+                long name of the suite for
+                :class:`~robot.model.suitestatistics.SuiteStatistics`
+                or name of the tag for
+                :class:`~robot.model.tagstatistics.TagStatistics`
+    :ivar passed: Number of passed tests.
+    :ivar failed: Number of failed tests.
+    :ivar elapsed: Number of milliseconds it took to execute.
+    """
 
     def __init__(self, name):
         self.name = name
@@ -78,10 +91,21 @@ def visit(self, visitor):
 
 
 class TotalStat(Stat):
+    """Stores statistic values for a test run.
+
+    :ivar type: Always string `total`.
+    """
     type = 'total'
 
 
 class SuiteStat(Stat):
+    """Stores statistics values for a single suite.
+
+    :ivar id: Identifier of the suite, e.g. `s1-s2`.
+    :ivar elapsed: Number of milliseconds it took to execute this suite,
+                   including sub-suites.
+    :ivar type: Always string `suite`
+    """
     type = 'suite'
 
     def __init__(self, suite):
@@ -102,6 +126,18 @@ def add_stat(self, other):
 
 
 class TagStat(Stat):
+    """Stores statistic values for a single tag.
+
+    :ivar doc: Documentation of tag as a string.
+    :ivar links: List of tuples in which the first value is the link URL and
+                 the second is the link title. An empty list by default.
+    :ivar critical: ``True`` if tag is considered critical, ``False`` otherwise.
+    :ivar non_critical: ``True`` if tag is considered non-critical, ``False``
+                        otherwise.
+    :ivar combined: Pattern as a string if the tag is combined, an empty string
+                    otherwise.
+    :ivar type: Always string `tag`.
+    """
     type = 'tag'
 
     def __init__(self, name, doc='', links=None, critical=False,
@@ -115,6 +151,10 @@ def __init__(self, name, doc='', links=None, critical=False,
 
     @property
     def info(self):
+        """Returns additional information of the tag statistics
+           are about. Either `critical`, `non-critical`, `combined` or an
+           empty string.
+        """
         if self.critical:
             return 'critical'
         if self.non_critical:
diff --git a/src/robot/model/suitestatistics.py b/src/robot/model/suitestatistics.py
@@ -16,6 +16,11 @@
 
 
 class SuiteStatistics(object):
+    """Container for suite statistics.
+
+    :ivar stat: Instance of :class:`~robot.model.stats.SuiteStat`.
+    :ivar suites: List of :class:`~robot.model.testsuite.TestSuite` objects.
+    """
 
     def __init__(self, suite):
         self.stat = SuiteStat(suite)
diff --git a/src/robot/model/tagstatistics.py b/src/robot/model/tagstatistics.py
@@ -22,6 +22,15 @@
 
 
 class TagStatistics(object):
+    """Container for tag statistics.
+
+    :ivar tags: Dictionary, where key is the name of the tag
+                as a string and value is an instance of
+                :class:`~robot.model.stats.TagStat`.
+    :ivar combined: Dictionary, where key is the name
+                    of the created tag as a string and value is an instance of
+                    :class:`~robot.model.stats.TagStat`.
+    """
 
     def __init__(self, combined_stats):
         self.tags = NormalizedDict(ignore=['_'])
diff --git a/src/robot/model/totalstatistics.py b/src/robot/model/totalstatistics.py
@@ -17,6 +17,13 @@
 
 
 class TotalStatistics(object):
+    """Container for total statistics.
+
+    :ivar critical: Instance of :class:`~robot.model.stats.TotalStat` for
+                    critical tests.
+    :ivar all: Instance of :class:`~robot.model.stats.TotalStat` for
+               all the tests, including critical.
+    """
 
     def __init__(self):
         self.critical = TotalStat('Critical Tests')
@@ -30,6 +37,12 @@ def __iter__(self):
 
     @property
     def message(self):
+        """Returns a summary of total statistics in a string representation,
+        for example::
+
+            2 critical tests, 1 passed, 1 failed
+            2 tests total, 1 passed, 1 failed
+        """
         ctotal, cend, cpass, cfail = self._get_counts(self.critical)
         atotal, aend, apass, afail = self._get_counts(self.all)
         return ('%d critical test%s, %d passed, %d failed\n'
diff --git a/src/robot/result/executionerrors.py b/src/robot/result/executionerrors.py
@@ -19,6 +19,13 @@
 
 
 class ExecutionErrors(object):
+    """Represents errors occurred during the execution of tests.
+
+    An error might be, for example, that importing a library has failed.
+
+    :ivar messages: A list-like object of :class:`~robot.model.message.Message`
+                    instances.
+    """
     message_class = Message
 
     def __init__(self, messages=None):
