TomDoc some things.

lib/jekyll/filters.rb

@@ -3,18 +3,43 @@ require 'uri'
 module Jekyll
 
   module Filters
+    # Convert a Textile string into HTML output.
+    #
+    # input - The Textile String to convert.
+    #
+    # Returns the HTML formatted String.
     def textilize(input)
       TextileConverter.new.convert(input)
     end
 
+    # Format a date in short format e.g. "27 Jan 2011".
+    #
+    # date - the Time to format.
+    #
+    # Returns the formatting String.
     def date_to_string(date)
       date.strftime("%d %b %Y")
     end
 
+    # Format a date in long format e.g. "27 January 2011".
+    #
+    # date - The Time to format.
+    #
+    # Returns the formatted String.
     def date_to_long_string(date)
       date.strftime("%d %B %Y")
     end
 
+    # Format a date for use in XML.
+    #
+    # date - The Time to format.
+    #
+    # Examples
+    #
+    #   date_to_xmlschema(Time.now)
+    #   # => "2011-04-24T20:34:46+08:00"
+    #
+    # Returns the formatted String.
     def date_to_xmlschema(date)
       date.xmlschema
     end
@@ -23,6 +48,17 @@ module Jekyll
       CGI.escapeHTML(input)
     end
 
+    # CGI escape a string for use in a URL. Replaces any special characters
+    # with appropriate %XX replacements.
+    #
+    # input - The String to escape.
+    #
+    # Examples
+    #
+    #   cgi_escape('foo,bar;baz?')
+    #   # => "foo%2Cbar%3Bbaz%3F"
+    #
+    # Returns the escaped String.
     def cgi_escape(input)
       CGI::escape(input)
     end
@@ -31,10 +67,26 @@ module Jekyll
       URI.escape(input)
     end
 
+    # Count the number of words in the input string.
+    #
+    # input - The String on which to operate.
+    #
+    # Returns the Integer word count.
     def number_of_words(input)
       input.split.length
     end
 
+    # Join an array of things into a string by separating with commes and the
+    # word "and" for the last one.
+    #
+    # array - The Array of Strings to join.
+    #
+    # Examples
+    #
+    #   array_to_sentence_string(["apples", "oranges", "grapes"])
+    #   # => "apples, oranges, and grapes"
+    #
+    # Returns the formatted String.
     def array_to_sentence_string(array)
       connector = "and"
       case array.length

lib/jekyll/layout.rb

@@ -3,16 +3,23 @@ module Jekyll
   class Layout
     include Convertible
 
-    attr_accessor :site
+    # Gets the Site object.
+    attr_reader :site
+
+    # Gets/Sets the extension of this layout.
     attr_accessor :ext
-    attr_accessor :data, :content
+
+    # Gets/Sets the Hash that holds the metadata for this layout.
+    attr_accessor :data
+
+    # Gets/Sets the content of this layout.
+    attr_accessor :content
 
     # Initialize a new Layout.
-    #   +site+ is the Site
-    #   +base+ is the String path to the <source>
-    #   +name+ is the String filename of the post file
     #
-    # Returns <Page>
+    # site - The Site.
+    # base - The String path to the source.
+    # name - The String filename of the post file.
     def initialize(site, base, name)
       @site = site
       @base = base
@@ -24,10 +31,11 @@ module Jekyll
       self.read_yaml(base, name)
     end
 
-    # Extract information from the layout filename
+    # Extract information from the layout filename.
-    #   +name+ is the String filename of the layout file
     #
-    # Returns nothing
+    # name - The String filename of the layout file.
+    #
+    # Returns nothing.
     def process(name)
       self.ext = File.extname(name)
     end

lib/jekyll/page.rb

@@ -8,12 +8,11 @@ module Jekyll
     attr_accessor :data, :content, :output
 
     # Initialize a new Page.
-    #   +site+ is the Site
-    #   +base+ is the String path to the <source>
-    #   +dir+ is the String path between <source> and the file
-    #   +name+ is the String filename of the file
     #
-    # Returns <Page>
+    # site - The Site object.
+    # base - The String path to the source.
+    # dir  - The String path between the source and the file.
+    # name - The String filename of the file.
     def initialize(site, base, dir, name)
       @site = site
       @base = base
@@ -26,22 +25,24 @@ module Jekyll
 
     # The generated directory into which the page will be placed
     # upon generation. This is derived from the permalink or, if
-    # permalink is absent, set to '/'
+    # permalink is absent, we be '/'
     #
-    # Returns <String>
+    # Returns the String destination directory.
     def dir
       url[-1, 1] == '/' ? url : File.dirname(url)
     end
 
-    # The full path and filename of the post.
+    # The full path and filename of the post. Defined in the YAML of the post
-    # Defined in the YAML of the post body
+    # body.
-    # (Optional)
     #
-    # Returns <String>
+    # Returns the String permalink or nil if none has been set.
     def permalink
       self.data && self.data['permalink']
     end
 
+    # The template of the permalink.
+    #
+    # Returns the template String.
     def template
       if self.site.permalink_style == :pretty && !index? && html?
         "/:basename/"
@@ -50,10 +51,9 @@ module Jekyll
       end
     end
 
-    # The generated relative url of this page
+    # The generated relative url of this page. e.g. /about.html.
-    # e.g. /about.html
     #
-    # Returns <String>
+    # Returns the String url.
     def url
       return @url if @url
 
@@ -74,20 +74,22 @@ module Jekyll
       @url
     end
 
-    # Extract information from the page filename
+    # Extract information from the page filename.
-    #   +name+ is the String filename of the page file
     #
-    # Returns nothing
+    # name - The String filename of the page file.
+    #
+    # Returns nothing.
     def process(name)
       self.ext = File.extname(name)
       self.basename = name[0 .. -self.ext.length-1]
     end
 
     # Add any necessary layouts to this post
-    #   +layouts+ is a Hash of {"name" => "layout"}
-    #   +site_payload+ is the site payload hash
     #
-    # Returns nothing
+    # layouts      - The Hash of {"name" => "layout"}.
+    # site_payload - The site payload Hash.
+    #
+    # Returns nothing.
     def render(layouts, site_payload)
       payload = {
         "page" => self.to_liquid,
@@ -97,6 +99,9 @@ module Jekyll
       do_layout(payload, layouts)
     end
 
+    # Convert this Page's data to a Hash suitable for use by Liquid.
+    #
+    # Returns the Hash representation of this Page.
     def to_liquid
       self.data.deep_merge({
         "url"        => File.join(@dir, self.url),
@@ -104,20 +109,23 @@ module Jekyll
     end
 
     # Obtain destination path.
-    #   +dest+ is the String path to the destination dir
     #
-    # Returns destination file path.
+    # dest - The String path to the destination dir.
+    #
+    # Returns the destination file path String.
     def destination(dest)
-      # The url needs to be unescaped in order to preserve the correct filename
+      # The url needs to be unescaped in order to preserve the correct
+      # filename.
       path = File.join(dest, @dir, CGI.unescape(self.url))
       path = File.join(path, "index.html") if self.url =~ /\/$/
       path
     end
 
     # Write the generated page file to the destination directory.
-    #   +dest+ is the String path to the destination dir
     #
-    # Returns nothing
+    # dest - The String path to the destination dir.
+    #
+    # Returns nothing.
     def write(dest)
       path = destination(dest)
       FileUtils.mkdir_p(File.dirname(path))
@@ -126,14 +134,17 @@ module Jekyll
       end
     end
 
+    # Returns the object as a debug String.
     def inspect
       "#<Jekyll:Page @name=#{self.name.inspect}>"
     end
 
+    # Returns the Boolean of whether this Page is HTML or not.
     def html?
       output_ext == '.html'
     end
 
+    # Returns the Boolean of whether this Page is an index file or not.
     def index?
       basename == 'index'
     end