Improve documentation

History.txt

@@ -4,6 +4,7 @@
 * Table.map_headers! will fail with a decent error message when 0 or 2+ headers are matched. (Aslak Hellesøy)
 
 === New Features
+* The public API is documented and there is a new :sdoc task to generate nice searchable API docs.
 * Add :default => :cucumber when setting up Rake tasks for Cucumber in Rails (Aslak Hellesøy)
 * New When /^I fill in "([^\"]*)" for "([^\"]*)"$/ Webrat step for Rails (Aslak Hellesøy)
 

Manifest.txt

@@ -289,7 +289,8 @@ gem_tasks/flog.rake
 gem_tasks/gemspec.rake
 gem_tasks/rspec.rake
 gem_tasks/sass.rake
-gem_tasks/yard.rake
+gem_tasks/sdoc.rake
+lib/README.rdoc
 lib/autotest/cucumber.rb
 lib/autotest/cucumber_mixin.rb
 lib/autotest/cucumber_rails.rb
@@ -396,7 +397,6 @@ spec/cucumber/ast/scenario_spec.rb
 spec/cucumber/ast/step_collection_spec.rb
 spec/cucumber/ast/step_spec.rb
 spec/cucumber/ast/table_spec.rb
-spec/cucumber/ast/visitor_spec.rb
 spec/cucumber/broadcaster_spec.rb
 spec/cucumber/cli/configuration_spec.rb
 spec/cucumber/cli/drb_client_spec.rb

gem_tasks/features.rake

@@ -3,6 +3,7 @@ require 'cucumber/rake/task'
 
 Cucumber::Rake::Task.new do |t|
   t.cucumber_opts = %w{--format progress}
+  t.rcov = ENV['RCOV']
 end
 
 Cucumber::Rake::Task.new('pretty') do |t|

gem_tasks/sdoc.rake

@@ -0,0 +1,7 @@
+require 'sdoc' # and use your RDoc task the same way you used it before
+
+Rake::RDocTask.new(:sdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc/sdoc'
+  rdoc.options += %w{--fmt shtml -N --webcvs=http://github.com/aslakhellesoy/cucumber/blob/v0.3.96/%s --title "Cucumber API" --threads 4 --main README --exclude cucumber/parser lib}
+  rdoc.template = 'direct' # lighter template used on railsapi.com
+end

lib/README.rdoc

@@ -0,0 +1,12 @@
+= Cucumber API
+
+This is the public API of Cucumber. The public API includes the classes, modules
+and methods you can use if you are a user of Cucumber. It also applies to you if
+you're developing a 3rd party tool that integrates with Cucumber.
+
+== Internal API
+
+Cucumber has more classes, modules and methods than what you can see in the public
+API. If you decide to dive into the source code and make use of an API that isn't
+part of this documentation - beware that this API might change at any time. If you
+want a particular internal API to be promoted to the public API - let us know.

lib/cucumber/ast/background.rb

@@ -2,7 +2,7 @@
 
 module Cucumber
   module Ast
-    class Background
+    class Background #:nodoc:
       include FeatureElement
       attr_reader :feature_elements
 

lib/cucumber/ast/comment.rb

@@ -7,7 +7,7 @@ module Ast
     #
     # This gets parsed into a Comment with value <tt>"# Lorem ipsum\n# dolor sit amet\n"</tt>
     #
-    class Comment
+    class Comment #:nodoc:
       def initialize(value)
         @value = value
       end

lib/cucumber/ast/examples.rb

@@ -1,6 +1,6 @@
 module Cucumber
   module Ast
-    class Examples
+    class Examples #:nodoc:
       def initialize(line, keyword, name, outline_table)
         @keyword, @name, @outline_table = keyword, name, outline_table
       end

lib/cucumber/ast/feature.rb

@@ -1,7 +1,7 @@
 module Cucumber
   module Ast
     # Represents the root node of a parsed feature.
-    class Feature
+    class Feature #:nodoc:
       attr_accessor :file, :language
       attr_writer :features
       attr_reader :name

lib/cucumber/ast/feature_element.rb

@@ -1,7 +1,7 @@
 require 'enumerator'
 
 module Cucumber
-  module FeatureElement
+  module FeatureElement #:nodoc:
     attr_writer :feature
 
     def attach_steps(steps)

lib/cucumber/ast/features.rb

@@ -1,6 +1,6 @@
 module Cucumber
   module Ast
-    class Features
+    class Features #:nodoc:
       include Enumerable
 
       attr_reader :duration

lib/cucumber/ast/outline_table.rb

@@ -1,6 +1,6 @@
 module Cucumber
   module Ast
-    class OutlineTable < Table
+    class OutlineTable < Table #:nodoc:
       def initialize(raw, scenario_outline)
         super(raw)
         @scenario_outline = scenario_outline
@@ -44,7 +44,7 @@ def visit_scenario_name(visitor, row)
         @scenario_outline.visit_scenario_name(visitor, row)
       end
 
-      class ExampleRow < Cells
+      class ExampleRow < Cells #:nodoc:
         attr_reader :scenario_outline # https://rspec.lighthouseapp.com/projects/16211/tickets/342
 
         def create_step_invocations!(scenario_outline)

lib/cucumber/ast/py_string.rb

@@ -16,7 +16,7 @@ module Ast
     #
     # Note how the indentation from the source is stripped away.
     #
-    class PyString
+    class PyString #:nodoc:
       def self.default_arg_name
         "string"
       end

lib/cucumber/ast/scenario.rb

@@ -2,7 +2,7 @@
 
 module Cucumber
   module Ast
-    class Scenario
+    class Scenario #:nodoc:
       include FeatureElement
 
       attr_reader :name, :line

lib/cucumber/ast/scenario_outline.rb

@@ -1,9 +1,9 @@
 module Cucumber
   module Ast
-    class ScenarioOutline
+    class ScenarioOutline #:nodoc:
       include FeatureElement
 
-      module ExamplesArray
+      module ExamplesArray #:nodoc:
         def accept(visitor)
           return if $cucumber_interrupted
           each do |examples|

lib/cucumber/ast/step.rb

@@ -3,7 +3,7 @@
 
 module Cucumber
   module Ast
-    class Step
+    class Step #:nodoc:
       attr_reader :line, :keyword, :name, :multiline_arg
       attr_writer :step_collection, :options
       attr_accessor :feature_element, :exception

lib/cucumber/ast/step_collection.rb

@@ -1,7 +1,7 @@
 module Cucumber
   module Ast
     # Holds an Array of Step or StepDefinition
-    class StepCollection
+    class StepCollection #:nodoc:
       include Enumerable
 
       def initialize(steps)

lib/cucumber/ast/step_invocation.rb

@@ -2,7 +2,7 @@
 
 module Cucumber
   module Ast
-    class StepInvocation
+    class StepInvocation #:nodoc:
       attr_writer :step_collection, :background
       attr_reader :name, :matched_cells, :status, :reported_exception
       attr_accessor :exception