[DOC] About the Examples moved to separate file

.gitignore

@@ -2,7 +2,6 @@
 /.yardoc
 /_yardoc/
 /coverage/
-/doc/
 /pkg/
 /spec/reports/
 /tmp/

doc/net-http/examples.rdoc

@@ -0,0 +1,30 @@
+Examples here assume that <tt>net/http</tt> has been required
+(which also requires +uri+):
+
+  require 'net/http'
+
+Many code examples here use these example websites:
+
+- https://jsonplaceholder.typicode.com.
+- http://example.com.
+
+Some examples also assume these variables:
+
+  uri = URI('https://jsonplaceholder.typicode.com')
+  uri.freeze # Examples may not modify.
+  hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+  port = uri.port         # => 443
+
+So that example requests may be written as:
+
+  Net::HTTP.get(uri)
+  Net::HTTP.get(hostname, '/index.html')
+  Net::HTTP.start(hostname) do |http|
+    http.get('/todos/1')
+    http.get('/todos/2')
+  end
+
+An example that needs a modified URI first duplicates +uri+, then modifies the duplicate:
+
+  _uri = uri.dup
+  _uri.path = '/todos/1'

lib/net/http.rb

@@ -98,36 +98,7 @@ class HTTPHeaderSyntaxError < StandardError; end
   #
   # == About the Examples
   #
-  # Examples here assume that <tt>net/http</tt> has been required
-  # (which also requires +uri+):
-  #
-  #   require 'net/http'
-  #
-  # Many code examples here use these example websites:
-  #
-  # - https://jsonplaceholder.typicode.com.
-  # - http://example.com.
-  #
-  # Some examples also assume these variables:
-  #
-  #   uri = URI('https://jsonplaceholder.typicode.com')
-  #   uri.freeze # Examples may not modify.
-  #   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-  #   port = uri.port         # => 443
-  #
-  # So that example requests may be written as:
-  #
-  #   Net::HTTP.get(uri)
-  #   Net::HTTP.get(hostname, '/index.html')
-  #   Net::HTTP.start(hostname) do |http|
-  #     http.get('/todos/1')
-  #     http.get('/todos/2')
-  #   end
-  #
-  # An example that needs a modified URI first duplicates +uri+, then modifies:
-  #
-  #   _uri = uri.dup
-  #   _uri.path = '/todos/1'
+  # :include: doc/net-http/examples.rdoc
   #
   # == URIs
   #

lib/net/http/response.rb

@@ -4,27 +4,7 @@
 #
 # == About the Examples
 #
-# Examples here assume that <tt>net/http</tt> has been required
-# (which also requires +uri+):
-#
-#   require 'net/http'
-#
-# Many code examples here use these example websites:
-#
-# - https://jsonplaceholder.typicode.com.
-# - http://example.com.
-#
-# Some examples also assume these variables:
-#
-#   uri = URI('https://jsonplaceholder.typicode.com')
-#   uri.freeze # Examples may not modify.
-#   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
-#   port = uri.port         # => 443
-#
-# An example that needs a modified URI first duplicates +uri+, then modifies:
-#
-#   _uri = uri.dup
-#   _uri.path = '/todos/1'
+# :include: doc/net-http/examples.rdoc
 #
 # == Returned Responses
 #