Internal documentation, typos, remove misleading message

* Made MycroftSkill.remove_event() return a bool, preventing unnecessary/misleading message from being posted by MycroftSkill.cancel_scheduled_event()
* More doc and several minor renames around intent processing
* Several minor typo and doc corrections

mycroft/audio/main.py

@@ -101,7 +101,7 @@ def load_services(config, ws, path=None):
         Search though the service directory and load any services.
 
         Args:
-            config: configuration dicrt for the audio backends.
+            config: configuration dict for the audio backends.
             ws: websocket object for communication.
 
         Returns:

mycroft/client/enclosure/api.py

@@ -207,7 +207,7 @@ class EnclosureAPI:
             y (int): y offset for image
             refresh (bool): specify whether to clear the faceplate before
                             displaying the new image or not.
-                            Useful if you'd like to display muliple images
+                            Useful if you'd like to display multiple images
                             on the faceplate at once.
         """
         DisplayManager.set_active(self.name)

mycroft/client/enclosure/display_manager.py

@@ -22,6 +22,23 @@ from mycroft.util import get_ipc_directory
 from mycroft.util.log import LOG
 
 
+# The DisplayManager provides "state" for the visual representation associated
+# with this Mycroft instance.  The current states are:
+#   ActiveSkill - The skill that last interacted with the display via the
+#                  Enclosure API.
+#
+# Currently, a wakeword sets the ActiveSkill to "wakeword", which will auto
+# clear after 10 seconds.
+#
+# A skill is set to Active when it matches an intent, outputs audio, or
+# changes the display via the EnclosureAPI()
+#
+# A skill is automatically cleared from Active two seconds after audio
+# output is spoken, or 2 seconds after resetting the disply.
+#
+# So it is common to have "" as the active skill.
+
+
 def _write_data(dictionary):
     """Writes the parama as JSON to the
         IPC dir (/tmp/mycroft/ipc/managers)

mycroft/skills/core.py

@@ -255,7 +255,7 @@ class MycroftSkill(object):
         self.file_system = FileSystemAccess(join('skills', self.name))
         self.registered_intents = []
         self.log = LOG.create_logger(self.name)
-        self.reload_skill = True
+        self.reload_skill = True  # allow reloading
         self.events = []
         self.skill_id = 0
 
@@ -679,11 +679,16 @@ class MycroftSkill(object):
 
             Args:
                 name: Name of Intent or Scheduler Event
+            Returns:
+                bool: True if found and removed, False if not found
         """
+        removed = False
         for _name, _handler in self.events:
             if name == _name:
                 self.events.remove((_name, _handler))
                 self.emitter.remove(_name, _handler)
+                removed = True
+        return removed
 
     def register_intent(self, intent_parser, handler, need_self=False):
         """
@@ -943,7 +948,7 @@ class MycroftSkill(object):
     def _schedule_event(self, handler, when, data=None, name=None,
                         repeat=None):
         """
-            Underlying method for schedle_event and schedule_repeating_event.
+            Underlying method for schedule_event and schedule_repeating_event.
             Takes scheduling information and sends it of on the message bus.
         """
         data = data or {}
@@ -1012,8 +1017,9 @@ class MycroftSkill(object):
         """
         unique_name = self._unique_name(name)
         data = {'event': unique_name}
-        self.remove_event(unique_name)
-        self.emitter.emit(Message('mycroft.scheduler.remove_event', data=data))
+        if self.remove_event(unique_name):
+            self.emitter.emit(Message('mycroft.scheduler.remove_event',
+                                      data=data))
 
     def get_scheduled_event_status(self, name):
         """

mycroft/skills/intent_service.py

@@ -170,13 +170,13 @@ class IntentService(object):
 
     def get_skill_name(self, skill_id):
         """
-            Get skill name from skill ID.
+        Get skill name from skill ID.
 
-            Args
-                skill_id: a skill id as encoded in Intent handlers.
+        Args:
+            skill_id: a skill id as encoded in Intent handlers.
 
-            Returns: (str) Skill name or the skill id if the skill
-                     wasn't found in the dict.
+        Returns: (str) Skill name or the skill id if the skill
+                 wasn't found in the dict.
         """
         return self.skill_names.get(int(skill_id), skill_id)
 
@@ -241,7 +241,9 @@ class IntentService(object):
 
     def send_metrics(self, intent, context, stopwatch):
         """
-            Send timing metrics to the backend.
+        Send timing metrics to the backend.
+
+        NOTE: This only applies to those with Opt In.
         """
         LOG.debug('Sending metric')
         ident = context['ident'] if context else None
@@ -259,7 +261,20 @@ class IntentService(object):
 
     def handle_utterance(self, message):
         """
-            Messagebus handler for the recognizer_loop:utterance message
+        Main entrypoint for handling user utterances with Mycroft skills
+        
+        Monitor the messagebus for 'recognizer_loop:utterance', typically
+        generated by a spoken interaction but potentially also from a CLI
+        or other method of injecting a 'user utterance' into the system.
+        
+        Utterances then work through this sequence to be handled:
+        1) Active skills attempt to handle using converse()
+        2) Adapt intent handlers
+        3) Padatious intent handlers
+        4) Other fallbacks
+
+        Args:
+            message (Message): The messagebus data
         """
         try:
             # Get language of the utterance
@@ -268,11 +283,12 @@ class IntentService(object):
 
             stopwatch = Stopwatch()
             with stopwatch:
-                # Parse the sentence
-                converse = self.parse_converse(utterances, lang)
+                # Give active skills an opportunity to handle the utterance
+                converse = self._converse(utterances, lang)
+                
                 if not converse:
-                    # no skill wants to handle utterance
-                    intent = self.parse_utterances(utterances, lang)
+                    # No conversation, use intent system to handle utterance
+                    intent = self._adapt_intent_match(utterances, lang)
 
             if converse:
                 # Report that converse handled the intent and return
@@ -281,10 +297,11 @@ class IntentService(object):
                               {'intent_type': 'converse'})
                 return
             elif intent:
-                # Send the message on to the intent handler
+                # Send the message to the intent handler
                 reply = message.reply(intent.get('intent_type'), intent)
             else:
-                # or if no match send sentence to fallback system
+                # Allow fallback system to handle utterance
+                # NOTE: Padatious intents are handled this way, too
                 reply = message.reply('intent_failure',
                                       {'utterance': utterances[0],
                                        'lang': lang})
@@ -293,7 +310,7 @@ class IntentService(object):
         except Exception as e:
             LOG.exception(e)
 
-    def parse_converse(self, utterances, lang):
+    def _converse(self, utterances, lang):
         """
             Converse, check if a recently invoked skill wants to
             handle the utterance and override normal adapt handling.
@@ -315,15 +332,16 @@ class IntentService(object):
                 return True
         return False
 
-    def parse_utterances(self, utterances, lang):
+    def _adapt_intent_match(self, utterances, lang):
         """
-            Parse the utteracne using adapt  to find a matching intent.
+            Run the Adapt engine to search for an matching the utterance
 
             Args:
                 utterances (list):  list of utterances
                 lang (string):      4 letter ISO language code
 
-            Returns: Intent structure, or None if no match was found.
+            Returns:
+                Intent structure, or None if no match was found.
         """
         best_intent = None
         for utterance in utterances:

mycroft/skills/main.py

@@ -165,9 +165,11 @@ def _get_last_modified_date(path):
         Get last modified date excluding compiled python files, hidden
         directories and the settings.json file.
 
-        Arg:
+        Args:
             path:   skill directory to check
-        Returns:    time of last change
+            
+        Returns:
+            int: time of last change
     """
     last_date = 0
     root_dir, subdirs, files = next(os.walk(path))