Permalink
Browse files

* added RDoc for httpclient/connection.rb. see #162.

  • Loading branch information...
1 parent be08f7f commit c6d461b861fee3e61e3ebf02ccc59f78af90759b nahi committed Dec 28, 2008
View
@@ -36,3 +36,7 @@ Rake::RDocTask.new("doc") do |rdoc|
rdoc.rdoc_files.include('lib/httpclient.rb')
end
+task 'tags' do
+ chdir 'lib'
+ sh 'rtags --vi httpclient.rb httpclient/*.rb'
+end
View
@@ -20,8 +20,6 @@
require 'httpclient/cookie'
-# == Description
-#
# The HTTPClient class provides several methods for accessing Web resources
# via HTTP.
#
@@ -179,13 +177,19 @@
#
# See head_async, get_async, post_async, put_async, delete_async,
# options_async, propfind_async, proppatch_async, and trace_async.
-# It immediately returns a HTTPClient::Connection instance as a result.
-#
-# connection = clnt.get_async('http://dev.ctor.org/')
-# io = connection.pop.content
-# while str = io.read(40)
-# p str
+# It immediately returns a HTTPClient::Connection instance as a returning value.
+#
+# connection = clnt.post_async(url, body)
+# print 'posting.'
+# while true
+# break if connection.finished?
+# print '.'
+# sleep 1
# end
+# puts '.'
+# res = connection.pop
+# p res.status
+# p res.content.read # res.content is an IO for the res of async method.
#
# === Shortcut methods
#
@@ -309,9 +313,10 @@ def attr_proxy(symbol, assignable = false)
# for loopback test. See test/* to see how to use it.
attr_proxy(:test_loopback_http_response)
+ # Default extheader for PROPFIND request.
PROPFIND_DEFAULT_EXTHEADER = { 'Depth' => '0' }
- # Create an HTTPClient instance which manages sessions, cookies, etc.
+ # Creates a HTTPClient instance which manages sessions, cookies, etc.
#
# HTTPClient.new takes 3 optional arguments for proxy url string,
# User-Agent String and From header String. User-Agent and From are embedded
@@ -487,9 +492,10 @@ def redirect_uri_callback=(redirect_uri_callback)
# Retrieves a web resource.
#
# uri:: a String or an URI object which reporesents an URL of web resource.
- # query:: a Hash or an Array of query part. e.g. { "a" => "b" }.
+ # query:: a Hash or an Array of query part of URL.
+ # e.g. { "a" => "b" } => 'http://host/part?a=b'.
# Give an array to pass multiple value like
- # [["a", "b"], ["a", "c"]].
+ # [["a", "b"], ["a", "c"]] => 'http://host/part?a=b&a=c'.
# extheader:: a Hash or an Array of extra headers. e.g.
# { 'Accept' => '*/*' } or
# [['Accept', 'image/jpeg'], ['Accept', 'image/png']].
@@ -513,9 +519,10 @@ def get_content(uri, query = nil, extheader = {}, &block)
# Posts a content.
#
# uri:: a String or an URI object which reporesents an URL of web resource.
- # body:: a Hash or an Array of body part. e.g. { "a" => "b" }.
+ # body:: a Hash or an Array of body part.
+ # e.g. { "a" => "b" } => 'a=b'.
# Give an array to pass multiple value like
- # [["a", "b"], ["a", "c"]].
+ # [["a", "b"], ["a", "c"]] => 'a=b&a=c'.
# When you pass a File as a value, it will be posted as a
# multipart/form-data. e.g. { 'upload' => file }
# extheader:: a Hash or an Array of extra headers. e.g.
@@ -616,12 +623,14 @@ def trace(uri, query = nil, body = nil, extheader = {}, &block)
#
# method:: HTTP method to be sent. method.to_s.upcase is used.
# uri:: a String or an URI object which reporesents an URL of web resource.
- # query:: a Hash or an Array of query part. e.g. { "a" => "b" }.
+ # query:: a Hash or an Array of query part of URL.
+ # e.g. { "a" => "b" } => 'http://host/part?a=b'
# Give an array to pass multiple value like
- # [["a", "b"], ["a", "c"]].
- # body:: a Hash or an Array of body part. e.g. { "a" => "b" }.
+ # [["a", "b"], ["a", "c"]] => 'http://host/part?a=b&a=c'
+ # body:: a Hash or an Array of body part.
+ # e.g. { "a" => "b" } => 'a=b'.
# Give an array to pass multiple value like
- # [["a", "b"], ["a", "c"]].
+ # [["a", "b"], ["a", "c"]] => 'a=b&a=c'.
# When the given method is 'POST' and the given body contains a file
# as a value, it will be posted as a multipart/form-data.
# e.g. { 'upload' => file }
View
@@ -1,6 +1,6 @@
# HTTPClient - HTTP client library.
# Copyright (C) 2000-2008 NAKAMURA, Hiroshi <nahi@ruby-lang.org>.
-
+#
# This program is copyrighted free software by NAKAMURA, Hiroshi. You can
# redistribute it and/or modify it under the same terms of Ruby's license;
# either the dual license version in 2003, or any later version.
@@ -1,6 +1,6 @@
# HTTPClient - HTTP client library.
# Copyright (C) 2000-2008 NAKAMURA, Hiroshi <nahi@ruby-lang.org>.
-
+#
# This program is copyrighted free software by NAKAMURA, Hiroshi. You can
# redistribute it and/or modify it under the same terms of Ruby's license;
# either the dual license version in 2003, or any later version.
@@ -9,18 +9,44 @@
class HTTPClient
- # magage a connection(one request and response to it).
+ # Represents a HTTP response to an asynchronous request. Async methods of
+ # HTTPClient such as get_async, post_async, etc. returns an instance of
+ # Connection.
+ #
+ # == How to use
+ #
+ # 1. Invoke HTTP method asynchronously and check if it's been finished
+ # periodically.
+ #
+ # connection = clnt.post_async(url, body)
+ # print 'posting.'
+ # while true
+ # break if connection.finished?
+ # print '.'
+ # sleep 1
+ # end
+ # puts '.'
+ # res = connection.pop
+ # p res.status
+ #
+ # 2. Read the response as an IO.
#
+ # connection = clnt.get_async('http://dev.ctor.org/')
+ # io = connection.pop.content
+ # while str = io.read(40)
+ # p str
+ # end
class Connection
attr_accessor :async_thread
- def initialize(header_queue = [], body_queue = [])
+ def initialize(header_queue = [], body_queue = []) # :nodoc:
@headers = header_queue
@body = body_queue
@async_thread = nil
@queue = Queue.new
end
+ # Checks if the asynchronous invocation has been finished or not.
def finished?
if !@async_thread
# Not in async mode.
@@ -35,14 +61,17 @@ def finished?
end
end
+ # Retrieves a HTTP::Message instance of HTTP response. Do not invoke this
+ # method twice for now. The second invocation will be blocked.
def pop
@queue.pop
end
- def push(result)
+ def push(result) # :nodoc:
@queue.push(result)
end
+ # Waits the completion of the asynchronous invocation.
def join
if @async_thread
@async_thread.join
Oops, something went wrong.

0 comments on commit c6d461b

Please sign in to comment.