From 16d15268181d536f1cf7126674619e942fc23b99 Mon Sep 17 00:00:00 2001
From: Thomas Pointhuber <thomas.pointhuber@gmx.at>
Date: Tue, 2 Sep 2014 16:48:18 +0200
Subject: [PATCH] add comments to deviantart engine

---
 searx/engines/deviantart.py | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/searx/engines/deviantart.py b/searx/engines/deviantart.py
index 298b9a397..29386f71d 100644
--- a/searx/engines/deviantart.py
+++ b/searx/engines/deviantart.py
@@ -1,35 +1,61 @@
+## Deviantart (Images)
+# 
+# @website     https://www.deviantart.com/
+# @provide-api yes (https://www.deviantart.com/developers/) (RSS)
+# 
+# @using-api   no (TODO, rewrite to api)
+# @results     HTML
+# @stable      no (HTML can change)
+# @parse       url, title, thumbnail
+#
+# @todo        rewrite to api
+
 from urllib import urlencode
 from urlparse import urljoin
 from lxml import html
 
+# engine dependent config
 categories = ['images']
+paging = True
 
+# search-url
 base_url = 'https://www.deviantart.com/'
 search_url = base_url+'search?offset={offset}&{query}'
 
-paging = True
-
 
+# do search-request
 def request(query, params):
     offset = (params['pageno'] - 1) * 24
+
     params['url'] = search_url.format(offset=offset,
                                       query=urlencode({'q': query}))
+
     return params
 
 
+# get response from search-request
 def response(resp):
     results = []
+
+    # return empty array if a redirection code is returned
     if resp.status_code == 302:
-        return results
+        return []
+
     dom = html.fromstring(resp.text)
+
+    # parse results
     for result in dom.xpath('//div[contains(@class, "tt-a tt-fh")]'):
         link = result.xpath('.//a[contains(@class, "thumb")]')[0]
         url = urljoin(base_url, link.attrib.get('href'))
         title_links = result.xpath('.//span[@class="details"]//a[contains(@class, "t")]')  # noqa
         title = ''.join(title_links[0].xpath('.//text()'))
         img_src = link.xpath('.//img')[0].attrib['src']
+
+        # append result
         results.append({'url': url,
                         'title': title,
                         'img_src': img_src,
                         'template': 'images.html'})
+
+    # return results
     return results