diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py
index 0ee18d220..5ffce16bd 100644
--- a/sphinx/directives/__init__.py
+++ b/sphinx/directives/__init__.py
@@ -94,6 +94,8 @@ class ObjectDescription(Directive):
         'rtype': l_('Return type'),
     }
 
+    # XXX refactor this
+
     def handle_doc_fields(self, node):
         """
         Convert field lists with known keys inside the description content into
diff --git a/sphinx/domains/__init__.py b/sphinx/domains/__init__.py
index 9e77cce8c..516eb2d17 100644
--- a/sphinx/domains/__init__.py
+++ b/sphinx/domains/__init__.py
@@ -172,7 +172,7 @@ from sphinx.domains.c import CDomain
 from sphinx.domains.std import StandardDomain
 from sphinx.domains.python import PythonDomain
 
-# this contains all registered domains
+# this contains all registered domains (XXX global state)
 all_domains = {
     'std': StandardDomain,
     'py': PythonDomain,
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index 1540f90b3..46b938981 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -327,6 +327,7 @@ class PyModule(Directive):
         targetnode = nodes.target('', '', ids=['module-' + modname], ismod=True)
         self.state.document.note_explicit_target(targetnode)
         ret = [modulenode, targetnode]
+        # XXX this behavior of the module directive is a mess...
         if 'platform' in self.options:
             platform = self.options['platform']
             modulenode['platform'] = platform
diff --git a/sphinx/environment.py b/sphinx/environment.py
index 09d15db3d..9626924f6 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -45,6 +45,7 @@ orig_directive_function = directives.directive
 
 class ElementLookupError(Exception): pass
 
+# XXX why isn't this a method of env?
 def lookup_domain_element(env, type, name):
     """Lookup a markup element (directive or role), given its name which can
     be a full name (with domain).
@@ -338,6 +339,7 @@ class BuildEnvironment:
         self.dlfiles = FilenameUniqDict()
 
         # temporary data storage while reading a document
+        # XXX find a better name
         self.doc_read_data = {}
 
         # Some magically present labels
diff --git a/sphinx/search.py b/sphinx/search.py
index 592f4cc6a..17a8354d1 100644
--- a/sphinx/search.py
+++ b/sphinx/search.py
@@ -150,8 +150,8 @@ class IndexBuilder(object):
 
     def get_objects(self, fn2index):
         rv = {}
-        ot = self._objtypes
-        on = self._objnames
+        otypes = self._objtypes
+        onames = self._objnames
         for domainname, domain in self.env.domains.iteritems():
             for fullname, type, docname, anchor, prio in domain.get_objects():
                 if docname not in fn2index:
@@ -162,15 +162,15 @@ class IndexBuilder(object):
                 prefix, name = rpartition(fullname, '.')
                 pdict = rv.setdefault(prefix, {})
                 try:
-                    i = ot[domainname, type]
+                    i = otypes[domainname, type]
                 except KeyError:
-                    i = len(ot)
-                    ot[domainname, type] = i
+                    i = len(otypes)
+                    otypes[domainname, type] = i
                     otype = domain.object_types.get(type)
                     if otype:
-                        on[i] = str(otype.lname)  # fire translation proxies
+                        onames[i] = str(otype.lname)  # fire translation proxies
                     else:
-                        on[i] = type
+                        onames[i] = type
                 pdict[name] = (fn2index[docname], i, prio)
         return rv
 
diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js
index 6b0000e8a..faef45941 100644
--- a/sphinx/themes/basic/static/searchtools.js
+++ b/sphinx/themes/basic/static/searchtools.js
@@ -362,6 +362,7 @@ var Search = {
             match = objects[prefix][name];
             descr = objnames[match[1]] + _(', in ') + titles[match[0]];
             // XXX the generated anchors are not generally correct
+            // XXX there may be custom prefixes
             result = [filenames[match[0]], fullname, '#'+fullname, descr];
             switch (match[2]) {
             case 1: objectResults.push(result); break;