diff --git a/lib/polecat/document.rb b/lib/polecat/document.rb
index 438ff28..a1001b5 100644
--- a/lib/polecat/document.rb
+++ b/lib/polecat/document.rb
@@ -7,24 +7,40 @@ module Document
     :value => nil
   }
 
-  def self.included o
-    o.extend(DocumentResource)
-    o.instance_variable_set :@attributes, {}
+  def self.included klass # :nodoc:
+    klass.extend(DocumentResource)
+    klass.instance_variable_set :@attributes, {}
   end
 
+  # creates a new document
+  #
+  # It is possible to create a new document with a hash, which has all values
+  # of the fields.
+  # Example:
+  # class Foo
+  #   include Polecat::Document
+  #
+  #   field :id
+  #   field :description
+  # end
+  # f = Foo.new :id => 1, :description => 'foo'
   def initialize fields = {}
     fields.each do |key, value|
       attribute_set key, value
     end
   end
 
+  # get an attribute of the document
   def attribute_get name
     attributes[name.to_sym][:value]
   end
 
+  # set an attribute of the document
   def attribute_set name, value
-    if attributes.has_key? name.to_sym
-      attributes[name.to_sym][:value] = value
+    name = name.to_sym
+    att = attributes
+    if att.has_key? name
+      att[name][:value] = value
     else
       raise ArgumentError, "attribute #{name} does not exist"
     end
diff --git a/lib/polecat/index.rb b/lib/polecat/index.rb
index 5b0c212..1532776 100644
--- a/lib/polecat/index.rb
+++ b/lib/polecat/index.rb
@@ -1,4 +1,8 @@
 class Polecat
+  # storage of documents
+  #
+  # This is the core of the search platform, the index. It stores the documents,
+  # stores and reads them and make them searchable.
   class Index
     attr_reader :path
 
@@ -36,15 +40,16 @@ class Polecat
 
     # read all stored documents from the index files into the index
     def read
-      if (File.exists?(@path + '/index.txt'))
-        @documents = Marshal.load(File.read(@path+'/index.txt'))
+      index_file = @path + '/index.txt'
+      if (File.exists? index_file)
+        @documents = Marshal.load(File.read(index_file))
       end
     end
 
     def flush
       @documents += @buffer
-      File.open @path + '/index.txt', 'w' do |f|
-        f.write Marshal.dump(@documents)
+      File.open @path + '/index.txt', 'w' do |file|
+        file.write Marshal.dump(@documents)
       end
     end