Merge branch 'docs' of https://github.com/icco/jekyll into icco-docs

lib/jekyll/filters.rb

@@ -57,6 +57,17 @@ module Jekyll
       date.xmlschema
     end
 
+    # XML escape a string for use. Replaces any special characters with
+    # appropriate HTML entity replacements.
+    #
+    # input - The String to escape.
+    #
+    # Examples
+    #
+    #   xml_escape('foo "bar" <baz>')
+    #   # => "foo &quot;bar&quot; &lt;baz&gt;"
+    #
+    # Returns the escaped String.
     def xml_escape(input)
       CGI.escapeHTML(input)
     end

lib/jekyll/post.rb

@@ -44,8 +44,8 @@ module Jekyll
         raise FatalException.new("#{msg} in #{@base}/#{name}")        
       end
 
-      #If we've added a date and time to the yaml, use that instead of the filename date
+      # If we've added a date and time to the yaml, use that instead of the
-      #Means we'll sort correctly.
+      # filename date Means we'll sort correctly.
       if self.data.has_key?('date')
         # ensure Time via to_s and reparse
         self.date = Time.parse(self.data["date"].to_s)
@@ -64,7 +64,10 @@ module Jekyll
       end
     end
 
-    # Spaceship is based on Post#date, slug
+    # Compares Post objects. First compares the Post date. If the dates are
+    # equal, it compares the Post slugs.
+    #
+    #   +other+ is the object we are comparing to.
     #
     # Returns -1, 0, 1
     def <=>(other)