Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documentation improvements.

  • Loading branch information...
commit 6b819fb1ee524f20e2f5f2a74f4e6f9d13b8f8ba 1 parent 3b6fa7a
@seancribbs seancribbs authored
View
1  Gemfile
@@ -5,6 +5,7 @@ source :rubygems
gemspec
gem 'bundler'
+gem 'bluecloth'
gem 'yard'
unless ENV['TRAVIS']
View
2  Guardfile
@@ -1,7 +1,7 @@
gemset = ENV['RVM_GEMSET'] || 'webmachine'
gemset = "@#{gemset}" unless gemset.to_s == ''
-rvms = %W[ 1.9.2 ].map {|v| "#{v}#{gemset}" }
+rvms = %W[ 1.8.7 1.9.2 jruby rbx ].map {|v| "#{v}#{gemset}" }
guard 'rspec', :cli => "--color --profile", :growl => true, :rvm => rvms do
watch(%r{^lib/webmachine/locale/.+$}) { "spec" }
View
10 Rakefile
@@ -1,6 +1,16 @@
require 'rubygems'
require 'rubygems/package_task'
+begin
+ require 'yard'
+ require 'yard/rake/yardoc_task'
+ YARD::Rake::YardocTask.new do |doc|
+ doc.files = Dir["lib/**/*.rb"] + ['README.md']
+ doc.options = ["-m", "markdown"]
+ end
+rescue LoadError
+end
+
def gemspec
$webmachine_gemspec ||= Gem::Specification.load("webmachine.gemspec")
end
View
2  lib/webmachine/decision/conneg.rb
@@ -215,7 +215,7 @@ def each
end
end
- # Like a {PriorityList}, but for {MediaTypes}, since they have
+ # Like a {PriorityList}, but for {MediaType}s, since they have
# parameters in addition to q.
# @private
class MediaTypeList < PriorityList
View
5 lib/webmachine/decision/flow.rb
@@ -6,8 +6,9 @@
module Webmachine
module Decision
# This module encapsulates all of the decisions in Webmachine's
- # flow-chart. These invoke {Resource} {Callbacks} to determine the
- # appropriate response code, headers, and body for the response.
+ # flow-chart. These invoke {Webmachine::Resource::Callbacks} methods to
+ # determine the appropriate response code, headers, and body for
+ # the response.
#
# This module is included into {FSM}, which drives the processing
# of the chart.
View
3  lib/webmachine/media_type.rb
@@ -51,6 +51,9 @@ def matches_all?
@type == "*/*" && @params.empty?
end
+ # @return [true,false] Are these two types strictly equal?
+ # @param other the other media type.
+ # @see MediaType.parse
def ==(other)
other = self.class.parse(other)
other.type == type && other.params == params
View
21 lib/webmachine/request.rb
@@ -1,20 +1,29 @@
require 'forwardable'
module Webmachine
- # This represents a single HTTP request sent from a client.
+ # Request represents a single HTTP request sent from a client. It
+ # should be instantiated by {Adapters} when a request is received
class Request
extend Forwardable
attr_reader :method, :uri, :headers, :body
attr_accessor :disp_path, :path_info, :path_tokens
- def initialize(meth, uri, headers, body)
- @method, @uri, @headers, @body = meth, uri, headers, body
+ # @param [String] method the HTTP request method
+ # @param [URI] uri the requested URI, including host, scheme and
+ # port
+ # @param [Headers] headers the HTTP request headers
+ # @param [String,#to_s,#each,nil] body the entity included in the
+ # request, if present
+ def initialize(method, uri, headers, body)
+ @method, @uri, @headers, @body = method, uri, headers, body
end
def_delegators :headers, :[]
- # @private
- def method_missing(m, *args)
+ # Enables quicker access to request headers by using a
+ # lowercased-underscored version of the header name, e.g.
+ # `if_unmodified_since`.
+ def method_missing(m, *args, &block)
if m.to_s =~ /^(?:[a-z0-9])+(?:_[a-z0-9]+)*$/i
# Access headers more easily as underscored methods.
self[m.to_s.tr('_', '-')]
@@ -23,7 +32,7 @@ def method_missing(m, *args)
end
end
- # Whether the request body is present.
+ # @return[true, false] Whether the request body is present.
def has_body?
!(body.nil? || body.empty?)
end
View
2  lib/webmachine/resource.rb
@@ -25,7 +25,7 @@ class Resource
attr_reader :request, :response
# Creates a new {Resource}, initializing it with the request and
- # response. Note that you may still override {#initialize} to
+ # response. Note that you may still override the `initialize` method to
# initialize your resource. It will be called after the request
# and response ivars are set.
# @param [Request] request the request object
View
2  lib/webmachine/resource/authentication.rb
@@ -4,6 +4,8 @@ class Resource
# {Webmachine::Resource} to assist in performing HTTP
# Authentication.
module Authentication
+ # Pattern for matching Authorization headers that use the Basic
+ # auth scheme.
BASIC_HEADER = /^Basic (.*)$/i.freeze
# A simple implementation of HTTP Basic auth. Call this from the
View
9 lib/webmachine/response.rb
@@ -33,10 +33,11 @@ def initialize
end
# Indicate that the response should be a redirect. This is only
- # used when processing a POST request in {Callbacks#process_post}
- # to indicate that the client should request another resource
- # using GET. Either pass the URI of the target resource, or
- # manually set the Location header using {#headers}.
+ # used when processing a POST request in
+ # {Resource::Callbacks#process_post} to indicate that the client
+ # should request another resource using GET. Either pass the URI
+ # of the target resource, or manually set the Location header
+ # using {#headers}.
# @param [String, URI] location the target of the redirection
def do_redirect(location=nil)
headers['Location'] = location.to_s if location
View
23 lib/webmachine/streaming.rb
@@ -1,25 +1,44 @@
module Webmachine
+ # Subclasses of this class implement means for streamed/chunked
+ # response bodies to be coerced to the negotiated character set and
+ # encoded automatically as they are output to the client.
+ # @api private
class StreamingEncoder
def initialize(resource, encoder, charsetter, body)
@resource, @encoder, @charsetter, @body = resource, encoder, charsetter, body
end
end
+ # Implements a streaming encoder for Enumerable response bodies, such as
+ # Arrays.
+ # @api private
class EnumerableEncoder < StreamingEncoder
include Enumerable
+ # Iterates over the body, encoding and yielding individual chunks
+ # of the response entity.
+ # @yield [chunk]
+ # @yieldparam [String] chunk a chunk of the response, encoded
def each
@body.each do |block|
- yield @resource.send(@encoder, @resource.send(@charsetter, block))
+ yield @resource.send(@encoder, @resource.send(@charsetter, block.to_s))
end
end
end
+ # Implements a streaming encoder for callable bodies, such as
+ # Proc. (essentially futures)
+ # @api private
class CallableEncoder < StreamingEncoder
+ # Encodes the output of the body Proc.
+ # @return [String]
def call
- @resource.send(@encoder, @resource.send(@charsetter, @body.call))
+ @resource.send(@encoder, @resource.send(@charsetter, @body.call.to_s))
end
+ # Converts this encoder into a Proc.
+ # @return [Proc] a closure that wraps the {#call} method
+ # @see #call
def to_proc
method(:call).to_proc
end
View
7 lib/webmachine/translation.rb
@@ -3,7 +3,14 @@
I18n.config.load_path << File.expand_path("../locale/en.yml", __FILE__)
module Webmachine
+ # Provides an interface to the I18n library specifically for
+ # {Webmachine}'s messages.
module Translation
+ # Interpolates an internationalized string.
+ # @param [String] key the name of the string to interpolate
+ # @param [Hash] options options to pass to I18n, including
+ # variables to interpolate.
+ # @return [String] the interpolated string
def t(key, options={})
::I18n.t(key, options.merge(:scope => :webmachine))
end
View
4 lib/webmachine/version.rb
@@ -1,4 +1,8 @@
module Webmachine
+ # Library version
VERSION = "0.2.0"
+
+ # String for use in "Server" HTTP response header, which includes
+ # the {VERSION}.
SERVER_STRING = "Webmachine-Ruby/#{VERSION}"
end
Please sign in to comment.
Something went wrong with that request. Please try again.