Feature #4100: Improve Net::HTTP documentation

• Status: Closed
• Assignee: -
• Target version: -

[drbrain (Eric Hodel)]

=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

[meta (mathew murphy)]

• File net-http-2010.patch net-http-2010.patch added

=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

[zenspider (Ryan Davis)]

=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

[drbrain (Eric Hodel)]

=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

[meta (mathew murphy)]

=begin
On Mon, Nov 29, 2010 at 19:09, Eric Hodel [e-mail] 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 <[e-mail]> 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/>

=end

[naruse (Yui NARUSE)]

=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

[naruse (Yui NARUSE)]

=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

[naruse (Yui NARUSE)]

=begin
Ah, HTTP_PROXY is from original doc.

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

[drbrain (Eric Hodel)]

=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

[drbrain (Eric Hodel)]

=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

[naruse (Yui NARUSE)]

=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:[e-mail]:8080,
but HTTP_PROXY=http://user:[e-mail]: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 [e-mail]

=end

[drbrain (Eric Hodel)]

• File net.http.rb.doc.2.patch net.http.rb.doc.2.patch added

=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

[drbrain (Eric Hodel)]

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

=begin

=end

[naruse (Yui NARUSE)]

• 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

[drbrain (Eric Hodel)]

=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