Project

General

Profile

Feature #4100

Improve Net::HTTP documentation

Added by drbrain (Eric Hodel) almost 9 years ago. Updated over 8 years ago.

Status:
Closed
Priority:
Normal
Assignee:
-
Target version:
-
[ruby-core:33469]

Description

=begin
The attached patch reorganizes and further explains how to use Net::HTTP.

The patch emphasizes using the persistent connection APIs over the simpler but more convenient non-persistent APIs.

The documentation now starts with an example using start/request, continues to describing how to extract data from a response, follow redirects and make POSTs which should be the most common operations.

Following that is examples for setting headers, basic authentication, streaming response bodies, HTTPS and proxies.

HTTPS documentation was moved from net/https.rb to the appropriate locations in Net::HTTP.

The final examples are for the Net::HTTP class methods ::get, ::get_response and ::post_form as they do not maintain persistent connections.

The HTTP request and response class sections have been modified to use rdoc lists.

The patch is on top of Mike Perham's patch in #4093 but moves the username/password Net::HTTP::Proxy example to the Net::HTTP::Proxy method.
=end


Files

net.http.rb.doc.patch (28.7 KB) net.http.rb.doc.patch drbrain (Eric Hodel), 11/30/2010 05:36 AM
net-http-2010.patch (35.7 KB) net-http-2010.patch Patches against 1.9 HEAD to improve net/http documentation meta (mathew murphy), 11/30/2010 08:26 AM
net.http.rb.doc.2.patch (25.3 KB) net.http.rb.doc.2.patch Revised patch that applies atop 29983 drbrain (Eric Hodel), 12/01/2010 02:06 AM

Associated revisions

Revision 80c21e35
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@29979 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 29979
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100

Revision 29979
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100

Revision 29979
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100

Revision 29979
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100

Revision 29979
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100

Revision 29979
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100

Revision 4bded50f
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by Eric Hodel ref #4100

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@29981 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 29981
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by Eric Hodel ref #4100

Revision 29981
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by Eric Hodel ref #4100

Revision 29981
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by Eric Hodel ref #4100

Revision 29981
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by Eric Hodel ref #4100

Revision 29981
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by Eric Hodel ref #4100

Revision 29981
Added by naruse (Yui NARUSE) almost 9 years ago

  • lib/net/http.rb: improve rdoc. patched by Eric Hodel ref #4100

History

#1

Updated by meta (mathew murphy) almost 9 years ago

=begin
I submitted some improvements to the net/http documentation back in 2005. Most of them were ignored, including several additional examples. Since the state of the documentation is currently being discussed on the web, I decided to go back and find my patch, and manually re-apply the changes that are still relevant, then regenerate a new patch against the current 1.9 Ruby HEAD.

Attached is the result. Hopefully there's not too much overlap with Eric Hodel's improvements, which I confess I didn't look at, and hopefully we can get the documentation improved more significantly this time around.

The most controversial part of my changes might be the apparent deletion of the exception/error class hierarchy from the overview; I did that because the class hierarchy is available elsewhere. I replaced the copy in the overview with an example of how to actually check errors, and a link to the full list.

I also added the warning in the relevant place about userinfo in URLs not being standard as per HTTP spec, noting that it's supported for historical reasons. Obviously, if the appropriate maintainer is going to support it going forward anyway, you can remove that note...
=end

#2

Updated by zenspider (Ryan Davis) almost 9 years ago

=begin

On Nov 29, 2010, at 15:26 , mathew murphy wrote:

I submitted some improvements to the net/http documentation back in 2005. Most of them were ignored, including several additional examples. Since the state of the documentation is currently being discussed on the web, I decided to go back and find my patch, and manually re-apply the changes that are still relevant, then regenerate a new patch against the current 1.9 Ruby HEAD.

awesome! thank you!

=end

#3

Updated by drbrain (Eric Hodel) almost 9 years ago

=begin
On Nov 29, 2010, at 15:26, mathew murphy wrote:

Issue #4100 has been updated by mathew murphy.

File net-http-2010.patch added

I submitted some improvements to the net/http documentation back in 2005. Most of them were ignored, including several additional examples. Since the state of the documentation is currently being discussed on the web, I decided to go back and find my patch, and manually re-apply the changes that are still relevant, then regenerate a new patch against the current 1.9 Ruby HEAD.

Attached is the result. Hopefully there's not too much overlap with Eric Hodel's improvements, which I confess I didn't look at, and hopefully we can get the documentation improved more significantly this time around.

Chunks 1, 3, 4, 5, 6 and possibly 2 will conflict with my patch.

The most controversial part of my changes might be the apparent deletion of the exception/error class hierarchy from the overview; I did that because the class hierarchy is available elsewhere. I replaced the copy in the overview with an example of how to actually check errors, and a link to the full list.

Your example for this could be simpler. I would write:

case response
when Net::HTTPSuccess then
when Net::HTTPRedirection then
when Net::HTTPServerError then

There is a redirect example from the existing documentation I adapted in my patch. I wonder if a specific mention of 304 Not Modified should be made as the response does not actually redirect anywhere. It would probably be easier to leave it for RFC 2616 to explain.

=end

#4

Updated by meta (mathew murphy) almost 9 years ago

=begin
On Mon, Nov 29, 2010 at 19:09, Eric Hodel drbrain@segment7.net wrote:

Chunks 1, 3, 4, 5, 6 and possibly 2 will conflict with my patch.

Does anyone else want to take a look at the conflicts, or shall I try
resolving my changes with the latest commit and coming up with another
patch?

Your example for this could be simpler. I would write:

case response
when Net::HTTPSuccess then
when Net::HTTPRedirection then
when Net::HTTPServerError then

I spend too much time writing Java where switch/case can't handle objects
:-)

mathew
--
URL:http://www.pobox.com/~meta/

On Mon, Nov 29, 2010 at 19:09, Eric Hodel <drbrain@segment7.net> wrote:
Chunks 1, 3, 4, 5, 6 and possibly 2 will conflict with my patch.Does anyone else want to take a look at the conflicts, or shall I try resolving my changes with the latest commit and coming up with another patch?
 Your example for this could be simpler.  I would write:

case response
when Net::HTTPSuccess then
when Net::HTTPRedirection then
when Net::HTTPServerError thenI spend too much time writing Java where switch/case can't handle objects :-) mathew-- <URL:http://www.pobox.com/~meta/>

=end

#5

Updated by naruse (Yui NARUSE) almost 9 years ago

=begin
First, I merged mathew's patch.
I didn't delete the exception/error class hierarchy
because class hierarchy overview with status code is not available.
=end

#6

Updated by naruse (Yui NARUSE) almost 9 years ago

=begin
Applying eric's patch, the result of http.rb is following:
Hunk #1 failed at 32.
Hunk #2 failed at 677.
Hunk #3 succeeded at 763 (offset 65 lines).
Hunk #4 failed at 918.
Hunk #5 succeeded at 1781 with fuzz 2 (offset 36 lines).
Hunk #6 succeeded at 2242 (offset 93 lines).
Hunk #7 succeeded at 2505 (offset 36 lines).

I read later Hunk #1.
I reject Hunk #2.
I'll apply Hunk #3.

In Hunk #4, why partly using HTTP_PROXY?
And it assumes HTTP_PROXY begins with http:// though it is not always URI.

I reject Hunk #5.
I'll apply Hunk #6 and #7.
=end

#7

Updated by naruse (Yui NARUSE) almost 9 years ago

=begin
Ah, HTTP_PROXY is from original doc.

I reject Hunk #7 because :nodoc: method is not a public API.
=end

#8

Updated by drbrain (Eric Hodel) almost 9 years ago

=begin
On Nov 29, 2010, at 21:08, Yui NARUSE wrote:

Issue #4100 has been updated by Yui NARUSE.

I reject Hunk #7 because :nodoc: method is not a public API.

Then should the examples switch from using #error! to #value?

(The example using #error! exists in 1.8.)

=end

#9

Updated by drbrain (Eric Hodel) almost 9 years ago

=begin
On Nov 29, 2010, at 19:09, Yui NARUSE wrote:

Issue #4100 has been updated by Yui NARUSE.

In Hunk #4, why partly using HTTP_PROXY?
And it assumes HTTP_PROXY begins with http:// though it is not always URI.

Ah, HTTP_PROXY is from original doc.

Should we correct the example to not assume that HTTP_PROXY is a URI?

Should we add a note mentioning that HTTP_PROXY may be either a host, host:port or URI? (RubyGems can accept all three values so I believe that all three have been found in the wild.)

=end

#10

Updated by naruse (Yui NARUSE) almost 9 years ago

=begin
(2010/12/01 1:30), Eric Hodel wrote:

On Nov 29, 2010, at 21:08, Yui NARUSE wrote:

Issue #4100 has been updated by Yui NARUSE.

I reject Hunk #7 because :nodoc: method is not a public API.

Then should the examples switch from using #error! to #value?

(The example using #error! exists in 1.8.)

Yes, it should use #value.

(2010/12/01 1:37), Eric Hodel wrote:

On Nov 29, 2010, at 19:09, Yui NARUSE wrote:

In Hunk #4, why partly using HTTP_PROXY?
And it assumes HTTP_PROXY begins with http:// though it is not always URI.

Ah, HTTP_PROXY is from original doc.

Should we correct the example to not assume that HTTP_PROXY is a URI?

Should we add a note mentioning that HTTP_PROXY may be either a host, host:port or URI?
(RubyGems can accept all three values so I believe that all three have been found in the wild.)

If we assume the value set as HTTP_PROXY has a valid URI form
(not a style like HTTP_PROXY=user:pass@example.com:8080,
but HTTP_PROXY=http://user:pass@example.com:8080)
proxy.host should use uri.hostname (yes, this is not #host, #hostname is correct
because of IPv6 address) and port should use uri.port.

--
NARUSE, Yui naruse@airemix.jp

=end

#11

Updated by drbrain (Eric Hodel) almost 9 years ago

=begin
I see you changed the proxy example, I agree.

I have fixed the examples to use #value instead of #error!

Attached is an updated patch that applies atop the existing changes and removes the rejected chunks.

Also, the usage documentation in lib/net/https.rb is removed as it has been moved to lib/net/http.rb. (Also, it was inaccessible to ri.)
=end

#12

Updated by drbrain (Eric Hodel) almost 9 years ago

  • File deleted (net.http.rb.doc.2.patch)

=begin

=end

#13

Updated by naruse (Yui NARUSE) almost 9 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100

=begin
This issue was solved with changeset r30001.
Eric, thank you for reporting this issue.
Your contribution to Ruby is greatly appreciated.
May Ruby be with you.

=end

#14

Updated by drbrain (Eric Hodel) almost 9 years ago

=begin
On Dec 1, 2010, at 07:17, Yui NARUSE wrote:

Issue #4100 has been updated by Yui NARUSE.

Status changed from Open to Closed
% Done changed from 0 to 100

This issue was solved with changeset r30001.

I committed r30006 to fix the positional wording of above/below since you placed the simple examples above the complex examples.

=end

Also available in: Atom PDF