[apycotlib] improve docstrings
authorDavid Douard <david.douard@logilab.fr>
Tue, 21 Oct 2014 23:15:12 +0200
changeset 1676 8f156ee8d9e7
parent 1675 533a3f8bbebb
child 1677 998cd9f5cbed
[apycotlib] improve docstrings
_apycotlib/writer.py
--- a/_apycotlib/writer.py	Tue Dec 23 14:18:51 2014 +0100
+++ b/_apycotlib/writer.py	Tue Oct 21 23:15:12 2014 +0200
@@ -1,8 +1,8 @@
-"""Writer sending data to a cubicweb instance which store it and may be used
-to display reports
+"""Writer classes: send data (execution reports) to an apycot cubicweb
+instance which stores and provides test execution reports
 
 :organization: Logilab
-:copyright: 2003-2010 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
+:copyright: 2003-2014 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
 :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
 """
 from __future__ import with_statement
@@ -41,7 +41,7 @@
 
 
 class AbstractLogWriter(object):
-
+    """Mixin to be used as a logging-like reporter"""
     def _unicode(self, something):
         if isinstance(something, str):
             return unicode(something, 'utf-8', 'replace')
@@ -98,8 +98,13 @@
 
 
 class BaseDataWriter(AbstractLogWriter):
-    """print execution message on stderr and store Test execution data to
-    a CubicWeb instance (using the apycot cube)
+    """A logging-like that print execution messages on stderr and
+    store Test execution data to a CubicWeb instance (using the apycot
+    cube)
+
+    Each logging statement is uploaded as a 4 columns tab-separated row:
+
+    <severity>TAB<path>TAB<line>TAB<logging message>
     """
 
     def __init__(self, cnxh, target_eid):
@@ -160,7 +165,10 @@
 
 
 class CheckDataWriter(BaseDataWriter):
-    """Writer intended to report Check level log and result."""
+    """Writer intended to report Check level log and result.
+
+    A Check is one step of a Test session
+    """
 
     def start(self, checker, name=None):
         """Register the given checker as started"""
@@ -192,10 +200,16 @@
 
 
 class TestDataWriter(BaseDataWriter):
-    """Writer intended to report Test level log and result."""
+    """Writer intended to report Test level log and result.
+
+    A test consist in a setup procedure (the install step) followed by
+    one or more checkers, each one executed in the environment set up
+    during the install step
+    """
 
     def make_check_writer(self):
-        """Return a CheckDataWriter suitable to write checker log and result within this test"""
+        """Return a CheckDataWriter suitable to write checker log and
+        result within this test"""
         self.refresh_log()
         return CheckDataWriter(self.cnxh, self.target_eid)