flesh out the introductory documentation

lib/rocco.rb

@@ -1,18 +1,45 @@
-# Rocco
-# =====
+# **Rocco** is a Ruby port of [Docco][do], the quick-and-dirty,
+# hundred-line-long, literate-programming-style documentation generator.
 #
-# Rocco is a quick-and-dirty literate-programming-style documentation
-# generator based *heavily* on [Docco](http://jashkenas.github.com/docco/).
+# Rocco reads Ruby source files and produces annotated source documentation
+# in HTML format. Comments are formatted with [Markdown][md] and presented
+# alongside syntax highlighted code so as to give an annotation effect.
+# This page is the result of running Rocco against its own source file.
+#
+# Most of this was written while waiting for [node.js][no] to build (so I
+# could use Docco!). Docco's gorgeous HTML and CSS are taken verbatim.
+# The main difference is that Rocco is written in Ruby instead of
+# [CoffeeScript][co] and may be a bit easier to obtain and install in
+# existing Ruby environments or where node doesn't run yet.
+#
+# Rocco can be installed with rubygems:
+#
+#     gem install rocco
+#
+# Once installed, the `rocco` command can be used to generate documentation
+# for a set of Ruby source files:
+#
+#     rocco lib/*.rb
+#
+# The HTML files are written to the current working directory.
+#
+# [no]: http://nodejs.org/
+# [do]: http://jashkenas.github.com/docco/
+# [co]: http://coffeescript.org/
+# [md]: http://daringfireball.net/projects/markdown/
 
+#### Prerequisites
 
 # The RDiscount library is required for Markdown processing.
 require 'rdiscount'
 
+#### Public Interface
+
+# `Rocco.new` takes a source `filename` and an optional `block`.
+# When `block` is given, it must read the contents of the file using
+# whatever means necessary and return it as a string. With no `block`, the
+# file is read to retrieve data.
 class Rocco
-  # `Rocco.new` takes a source `filename` and an optional `block` used to
-  # read the file's contents. When `block` is given, it must read the contents
-  # of the file using whatever means necessary and return it as a string.
-  # With no `block`, the file is read to retrieve data.
   def initialize(filename, &block)
     @file = filename
     @data =
@@ -21,25 +48,26 @@ class Rocco
       else
         File.read(filename)
       end
-
-    # Jump right into the parsing and highlighting phase.
+    # Jump right into parsing and highlighting.
     @sections = highlight(parse(@data))
   end
 
-  # The source filename.
+  # The filename as given to `Rocco.new`.
   attr_reader :file
 
   # A list of two-tuples representing each *section* of the source file. Each
-  # item in the list has the form `[docs_html, code_html]` and represents a
-  # single section.
-  #
-  # Both `docs_html` and `code_html` are strings containing the
-  # documentation and source code HTML, respectively.
+  # item in the list has the form: `[docs_html, code_html]`, where both
+  # elements are strings containing the documentation and source code HTML,
+  # respectively.
   attr_reader :sections
 
-  # Internal Parsing and Highlighting
-  # ---------------------------------
-  protected
+  # Generate HTML output for the entire document.
+  require 'rocco/layout'
+  def to_html
+    Rocco::Layout.new(self).render
+  end
+
+  #### Internal Parsing and Highlighting
 
   # Parse the raw file data into a list of two-tuples.
   def parse(data)
@@ -54,11 +82,7 @@ class Rocco
         end
         docs << line
       when /^\s*$/
-          if code.any?
         code << line
-          else
-            docs << line
-          end
       else
         code << line
       end
@@ -105,7 +129,7 @@ class Rocco
     # partial `<pre>` blocks. We'll add these back when we build to main
     # document.
     code_html = code_html.
-        split(/\n*<span class="c1"># DIVIDER<\/span>\n*/m).
+      split(/\n?<span class="c1"># DIVIDER<\/span>\n?/m).
       map { |code| code.sub(/\n?<div class="highlight"><pre>/m, '') }.
       map { |code| code.sub(/\n?<\/pre><\/div>\n/m, '') }
 
@@ -113,11 +137,4 @@ class Rocco
     # started with.
     docs_html.zip(code_html)
   end
-
-public
-  require 'rocco/layout'
-
-  def to_html
-    Rocco::Layout.new(self).render
-  end
 end

lib/rocco/layout.rb

@@ -8,7 +8,7 @@ class Rocco::Layout < Mustache
   end
 
   def title
-    @doc.file
+    File.basename(@doc.file)
   end
 
   def sections