add some documentation for improved discoverability

hoover/input.py

@@ -16,18 +16,25 @@ def get_handler(self, **kwargs):
         return LogglySyslogHandler(self.session, input=self, **kwargs)
 
     def search(self, q='', **kwargs):
+        '''Thin wrapper on LogglySession.search, restricting the search to
+        data from this input.'''
         q = '%s inputname:%s' % (q, self.name)
         return self.session.search(q, **kwargs)
 
     def facets(self, q='', **kwargs):
+        '''Thin wrapper on LogglySession.facets, restricting the search to
+        data from this input.'''
         q = '%s inputname:%s' % (q, self.name)
         return self.session.facets(q, **kwargs)
 
     def delete(self):
+        '''Deletes the input from your Loggly account.'''
         self.session._api_help('api/inputs/%s' % self.id, method='DELETE')
         self.session.inputs.remove(self)
 
     def set_discover(self, state=True):
+        '''Given state=True,False, puts the input into, or takes it out of
+        discovery mode.'''
         method = state and 'POST' or 'DELETE'
         self.session._api_help('api/inputs/%d/discover/' % self.id,
                               method=method)

hoover/session.py

@@ -66,6 +66,7 @@ def html_inputs(self):
         return [i for i in self.inputs if i.service['name'] == 'HTTP']
 
     def get_input_by_name(self, name):
+        '''Locates an input by name. Case insensitive.'''
         try:
             (result,) = [i for i in self.inputs
                          if i.name.lower() == name.lower()]
@@ -82,16 +83,29 @@ def config_inputs(self):
 
     @time_translate
     def search(self, q='*', **kwargs):
+        '''Thin wrapper on Loggly's text search API. First parameter is a query
+        string.'''
         kwargs['q'] = q
         return self._api_help('api/search', kwargs)
 
     @time_translate
     def facets(self, q='*', facetby='date', **kwargs):
+        '''Thin wrapper on Loggly's facet search API. facetby can be input, ip,
+        or a json parameter of the form json.foo'''
         kwargs['q'] = q
         return self._api_help('api/facets/%s' % facetby, kwargs)
 
     def create_input(self, name, service='syslogudp', description='',
                      json=False):
+        '''Creates a new input on your loggly account. Service can be any of:
+            syslogudp
+            syslogtcp
+            syslogudp_strip
+            syslogtcp_strip
+            syslog 514
+            HTTP
+            syslog_tls.
+        JSON can only be used with HTTP inputs.'''
         if json and service.lower() != 'http':
             raise ValueError("only HTTP inputs can use JSON")
         format = json and 'json' or 'text'