From: Eric Hodel <drbrain@...7.net>
Date: 2010-11-30T10:09:39+09:00
Subject: [ruby-core:33475] Re: [Ruby 1.9-Feature#4100] Improve Net::HTTP documentation

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.