From 934495b272397acef4ee62cc5b9907dafff4ba75 Mon Sep 17 00:00:00 2001
From: Nat Welch <nat@natwelch.com>
Date: Tue, 18 Dec 2012 22:42:42 -0800
Subject: [PATCH] Adds some random docs for stuff I saw while skimming the
 code.

---
 lib/jekyll/filters.rb | 11 +++++++++++
 lib/jekyll/post.rb    |  9 ++++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/lib/jekyll/filters.rb b/lib/jekyll/filters.rb
index eb61d84a..0012c25f 100644
--- a/lib/jekyll/filters.rb
+++ b/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
diff --git a/lib/jekyll/post.rb b/lib/jekyll/post.rb
index 3934b977..fdbc3d60 100644
--- a/lib/jekyll/post.rb
+++ b/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
-      #Means we'll sort correctly.
+      # If we've added a date and time to the yaml, use that instead of the
+      # 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)