made some more doc string and comment formatting improvements

Author: userzimmermann

robottools/library/keywords/__init__.py

@@ -43,8 +43,8 @@
 class Keyword(object):
     """The Keyword handler for Test Library instances.
 
-    - Provides inspection of names, args and docs.
-    - Gets called by Test Library's run_keyword().
+    * Provides inspection of Keyword name, arguments, and documentation.
+    * Instances get called by Test Libraries' ``.run_keyword()`` method.
     """
     def __init__(self, name, func, libinstance):
         """Initialize with Keyword's display `name`,
@@ -53,30 +53,34 @@ def __init__(self, name, func, libinstance):
         self.name = name
         self.func = func
         self.libinstance = libinstance
-        # Get all ContextHandler classes for which this Keyword
-        #  has context-specific implementations,
-        #  to implicitly provide additional <context>= switching kwargs:
+        # Get all ContextHandler-derived classes for which this Keyword
+        # has context-specific implementations,
+        # to implicitly provide additional context_name= switching kwargs:
         self.context_handlers = set(ctx.handler for ctx in func.contexts)
 
     @property
     def __doc__(self):
+        """The Keyword's documentation string,
+        taken from ``self.func.__doc__``.
+        """
         return self.func.__doc__
 
     @property
     def libname(self):
-        """The Test Library's class and display name.
+        """The Keyword's Test Library class name,
+        which also represents the Library's display name.
         """
         return type(self.libinstance).__name__
 
     @property
     def longname(self):
-        """The Keyword's full display name (TestLibraryName.Keyword Name).
+        """The Keyword's full display name (**TestLibraryName.Keyword Name**).
         """
         return '%s.%s' % (self.libname, self.name)
 
     def args(self):
         """Iterate the Keyword's argument spec in Robot's Dynamic API style,
-           usable by Test Library's get_keyword_arguments().
+           usable by Test Libraries' ``.get_keyword_arguments()`` method.
         """
         # First look for custom override args list:
         if self.func.args:
@@ -117,7 +121,7 @@ def args(self):
             yield '**options'
 
     def __call__(self, *args, **kwargs):
-        """Call the Keyword's function with the given arguments.
+        """Call the Keyword's actual function with the given arguments.
         """
         func = self.func
         # look for explicit <session>= and <context>= switching options

robottools/library/keywords/utils.py

@@ -35,9 +35,9 @@
 class KeywordName(str):
     """:class:`str` wrapper to work with Keyword names in a Robot way.
 
-    - Converts the given raw Keyword name (usually a function name)
+    * Converts the given raw Keyword name (usually a function name)
       to Capitalized Robot Style.
-    - Uses :func:`robot.utils.normalize`d conversions
+    * Uses :func:`robot.utils.normalize`d conversions
       (plain lowercase without spaces and underscores)
       for comparing and hashing.
     """
@@ -58,8 +58,8 @@ def __hash__(self):
 
 
 class KeywordsDict(object):
-    """Store Keyword functions or :class:`Keyword` objects
-       with :class:`KeywordName` keys.
+    """Store Keyword functions or :class:`robottools.Keyword` instances
+    with :class:`robottools.KeywordName` keys.
     """
     def __init__(self):
         self._dict = {}
@@ -89,6 +89,7 @@ def __nonzero__(self):
         return self.__bool__()
 
     def __dir__(self):
-        """The Keyword names in CamelCase.
+        """The Keyword names in CamelCase
+        to be used with :meth:`self.__getattr__`.
         """
         return [''.join(name.split()) for name in self._dict]