Edit docstrings to match style guidelines

mycroft/skills/core.py

@@ -370,26 +370,58 @@ class MycroftSkill(object):
 
     def translate(self, text, data=None):
         """
-        Translate a short string using dialog/<lang>/<text>.dialog
+        Load a translatable single string resource
-        This can be used for short phrases and words like "meters" or "hours"
+
+        The string is loaded from a file in the skill's dialog subdirectory
+          'dialog/<lang>/<text>.dialog'
+        The string is randomly chosen from the file and rendered, replacing
+        mustache placeholders with values found in the data dictionary.
+
+        Args:
+            text (str): The base filename  (no extension needed)
+            data (dict, optional): a JSON dictionary
+
+        Returns:
+            str: A randomly chosen string from the file
         """
         return self.dialog_renderer.render(text, data or {})
 
     def translate_template(self, template_name, data=None):
         """
-        Read a list of strings from dialog/<lang>/<teamplate>.template
+        Load a translatable template
-        This can be used for large blocks of text with parameters
+
-        that need to be localized
+        The strings are loaded from a template file in the skill's dialog
+        subdirectory.
+          'dialog/<lang>/<template_name>.template'
+        The strings are loaded and rendered, replacing mustache placeholders
+        with values found in the data dictionary.
+
+        Args:
+            template_name (str): The base filename (no extension needed)
+            data (dict, optional): a JSON dictionary
+
+        Returns:
+            list of str: The loaded template file
         """
         return self.__translate_file(template_name + '.template', data)
 
     def translate_list(self, list_name, data=None):
         """
-        Read a list of strings from dialog/<lang>/<list>.list
+        Load a list of translatable string resources
-        These values should be position dependent items, consistent
+
-        across languages. For example, there could be a "colors".list
+        The strings are loaded from a list file in the skill's dialog
-        which lists a set of all colors in a consistent order across
+        subdirectory.
-        all languages
+          'dialog/<lang>/<list_name>.list'
+        The strings are loaded and rendered, replacing mustache placeholders
+        with values found in the data dictionary.
+
+        Args:
+            list_name (str): The base filename (no extension needed)
+            data (dict, optional): a JSON dictionary
+
+        Returns:
+            list of str: The loaded list of strings with items in consistent
+                         positions regardless of the language.
         """
         return self.__translate_file(list_name + '.list', data)
 
@@ -624,10 +656,10 @@ class MycroftSkill(object):
             Speak a sentence.
 
             Args:
-                utterance:          sentence mycroft should speak
+                utterance (str):        sentence mycroft should speak
-                expect_response:    set to True if Mycroft should expect a
+                expect_response (bool): set to True if Mycroft should listen
-                                    response from the user and start listening
+                                        for a response immediately after
-                                    for response.
+                                        speaking the utterance.
         """
         # registers the skill as being active
         self.enclosure.register(self.name)
@@ -637,14 +669,14 @@ class MycroftSkill(object):
 
     def speak_dialog(self, key, data=None, expect_response=False):
         """
-            Speak sentance based of dialog file.
+            Speak a random sentence from a dialog file.
 
             Args
-                key: dialog file key (filname without extension)
+                key (str): dialog file key (filename without extension)
-                data: information to populate sentence with
+                data (dict): information used to populate sentence
-                expect_response:    set to True if Mycroft should expect a
+                expect_response (bool): set to True if Mycroft should listen
-                                    response from the user and start listening
+                                        for a response immediately after
-                                    for response.
+                                        speaking the utterance.
         """
         data = data or {}
         self.speak(self.dialog_renderer.render(key, data), expect_response)