From a428acec1c41eaee206f36fc2fdb41a0479bee60 Mon Sep 17 00:00:00 2001 From: Tom Preston-Werner Date: Sun, 8 May 2011 14:49:19 -0700 Subject: [PATCH] TomDoc some things. --- lib/jekyll/filters.rb | 52 +++++++++++++++++++++++++++++++++++ lib/jekyll/layout.rb | 28 ++++++++++++------- lib/jekyll/page.rb | 63 +++++++++++++++++++++++++------------------ 3 files changed, 107 insertions(+), 36 deletions(-) diff --git a/lib/jekyll/filters.rb b/lib/jekyll/filters.rb index 3356eadf..dbd9f511 100644 --- a/lib/jekyll/filters.rb +++ b/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 diff --git a/lib/jekyll/layout.rb b/lib/jekyll/layout.rb index bc048a5d..15845730 100644 --- a/lib/jekyll/layout.rb +++ b/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 - # +name+ is the String filename of the post file # - # Returns + # 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,13 +31,14 @@ module Jekyll self.read_yaml(base, name) end - # Extract information from the layout filename - # +name+ is the String filename of the layout file + # Extract information from the layout filename. # - # Returns nothing + # name - The String filename of the layout file. + # + # Returns nothing. def process(name) self.ext = File.extname(name) end end -end \ No newline at end of file +end diff --git a/lib/jekyll/page.rb b/lib/jekyll/page.rb index 03f03da2..a4a0f9f3 100644 --- a/lib/jekyll/page.rb +++ b/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 - # +dir+ is the String path between and the file - # +name+ is the String filename of the file # - # Returns + # 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 + # Returns the String destination directory. def dir url[-1, 1] == '/' ? url : File.dirname(url) end - # The full path and filename of the post. - # Defined in the YAML of the post body - # (Optional) + # The full path and filename of the post. Defined in the YAML of the post + # body. # - # Returns + # 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 - # e.g. /about.html + # The generated relative url of this page. e.g. /about.html. # - # Returns + # Returns the String url. def url return @url if @url @@ -74,20 +74,22 @@ module Jekyll @url end - # Extract information from the page filename - # +name+ is the String filename of the page file + # Extract information from the page filename. # - # 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,27 +99,33 @@ 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), "content" => self.content }) 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 "#" 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