Start documenting with RDoc

Author: oestrich

.gitignore

@@ -4,3 +4,4 @@ example/docs
 example/public/docs
 *.gem
 *.swp
+/html/

Gemfile

@@ -1,3 +1,5 @@
 source 'http://rubygems.org'
 
 gemspec
+
+gem 'inch'

Gemfile.lock

@@ -33,6 +33,7 @@ GEM
       xpath (~> 2.0)
     childprocess (0.3.9)
       ffi (~> 1.0, >= 1.0.11)
+    coderay (1.1.0)
     crack (0.4.1)
       safe_yaml (~> 0.9.0)
     cucumber (1.3.10)
@@ -48,7 +49,13 @@ GEM
       multi_json (~> 1.3)
     httpclient (2.3.4.1)
     i18n (0.6.5)
+    inch (0.4.5)
+      pry
+      sparkr (>= 0.2.0)
+      term-ansicolor
+      yard (~> 0.8.7)
     json (1.8.1)
+    method_source (0.8.2)
     mime-types (2.0)
     mini_portile (0.5.2)
     minitest (4.7.5)
@@ -57,6 +64,10 @@ GEM
     mustache (0.99.5)
     nokogiri (1.6.0)
       mini_portile (~> 0.5.0)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
     rack (1.5.2)
     rack-oauth2 (1.0.7)
       activesupport (>= 2.3)
@@ -82,15 +93,21 @@ GEM
       rack (~> 1.4)
       rack-protection (~> 1.4)
       tilt (~> 1.3, >= 1.3.4)
+    slop (3.5.0)
+    sparkr (0.4.1)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
     thread_safe (0.1.3)
       atomic
     tilt (1.4.1)
+    tins (1.1.0)
     tzinfo (0.3.38)
     webmock (1.16.0)
       addressable (>= 2.2.7)
       crack (>= 0.3.2)
     xpath (2.0.0)
       nokogiri (~> 1.3)
+    yard (0.8.7.4)
 
 PLATFORMS
   ruby
@@ -99,6 +116,7 @@ DEPENDENCIES
   aruba
   capybara
   fakefs
+  inch
   rack-oauth2 (>= 0.14.4)
   rack-test (>= 0.6.2)
   rake

Rakefile

@@ -6,3 +6,9 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => [:spec, :cucumber]
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rd|
+  rd.main = "README.md"
+  rd.rdoc_files.include("README.md", "lib/**/*.rb")
+end

lib/rspec_api_documentation.rb

@@ -3,6 +3,7 @@
 require 'cgi'
 require 'json'
 
+# Namespace for RspecApiDocumentation
 module RspecApiDocumentation
   extend ActiveSupport::Autoload
 
@@ -62,6 +63,13 @@ def self.documentations
     @documentations ||= configuration.map { |config| ApiDocumentation.new(config) }
   end
 
+  # Configures RspecApiDocumentation
+  #
+  # See RspecApiDocumentation::Configuration for more information on configuring.
+  #
+  #   RspecApiDocumentation.configure do |config|
+  #     config.docs_dir = "doc/api"
+  #   end
   def self.configure
     yield configuration if block_given?
   end

lib/rspec_api_documentation/client_base.rb

@@ -1,4 +1,7 @@
 module RspecApiDocumentation
+  # Base client class that documents all requests that go through it.
+  #
+  #  client.get("/orders", { :page => 2 }, { "Accept" => "application/json" })
   class ClientBase < Struct.new(:context, :options)
     include Headers
 

lib/rspec_api_documentation/configuration.rb

@@ -13,6 +13,23 @@ def groups
       @groups ||= []
     end
 
+    # Defines a new sub configuration
+    #
+    # Automatically sets the `filter` to the group name, and the `docs_dir` to
+    # a subfolder of the parent's `doc_dir` named the group name.
+    #
+    #   RspecApiDocumentation.configure do |config|
+    #     config.docs_dir = "doc/api"
+    #     config.define_group(:public) do |config|
+    #       # Default values
+    #       config.docs_dir = "doc/api/public"
+    #       config.filter = :public
+    #     end
+    #   end
+    #
+    # Params:
+    # +name+:: String name of the group
+    # +block+:: Block configuration block
     def define_group(name, &block)
       subconfig = self.class.new(self)
       subconfig.filter = name
@@ -79,6 +96,7 @@ def settings
       @settings ||= {}
     end
 
+    # Yields itself and sub groups to hook into the Enumerable module
     def each(&block)
       yield self
       groups.map { |g| g.each &block }

lib/rspec_api_documentation/dsl.rb

@@ -2,6 +2,16 @@
 require "rspec_api_documentation/dsl/endpoint"
 require "rspec_api_documentation/dsl/callback"
 
+# Custom describe block that sets metadata to enable the rest of RAD
+#
+#   resource "Orders", :meta => :data do
+#     # ...
+#   end
+#
+# Params:
+# +args+:: Glob of RSpec's `describe` arguments
+# +block+:: Block to pass into describe
+#
 def self.resource(*args, &block)
   options = if args.last.is_a?(Hash) then args.pop else {} end
   options[:api_doc_dsl] = :resource

lib/rspec_api_documentation/dsl/callback.rb

@@ -1,4 +1,5 @@
 module RspecApiDocumentation::DSL
+  # DSL Methods for testing server callbacks
   module Callback
     extend ActiveSupport::Concern
 

lib/rspec_api_documentation/dsl/endpoint.rb

@@ -3,6 +3,7 @@
 require 'rack/test/utils'
 
 module RspecApiDocumentation::DSL
+  # DSL methods available inside the RSpec example.
   module Endpoint
     extend ActiveSupport::Concern
     include Rack::Test::Utils
@@ -23,6 +24,7 @@ def example_request(description, params = {}, &block)
       end
 
       private
+
       # from rspec-core
       def relative_path(line)
         line = line.sub(File.expand_path("."), ".")