[ruby/open-uri] Improve URI.open documentation with usage example

This improves the `URI.open` method documentation by adding a code example requiring `open-uri` as a basic usage.

When reading the current documentation first, I didn't realize that `open-uri` was required to call the method.
I believe the improved version could be more helpful for new users.

```sh-session
$ ruby -r uri -e 'p URI.open("http://example.com")'
-e:1:in '<main>': private method 'open' called for module URI (NoMethodError)
```

Ref https://docs.ruby-lang.org/en/master/URI.html#method-c-open

Also, this improves formatting with code fonts for better readability.

https://github.com/ruby/open-uri/commit/f4400edc27

1 files changed, 9 insertions, 6 deletions

diff --git a/lib/open-uri.rb b/lib/open-uri.rb
index 5983c7368b..844865b13a 100644
--- a/lib/open-uri.rb
+++ b/lib/open-uri.rb
@@ -4,22 +4,25 @@ require 'stringio'
 require 'time'
 
 module URI
-  # Allows the opening of various resources including URIs.
+  # Allows the opening of various resources including URIs. Example:
   #
-  # If the first argument responds to the 'open' method, 'open' is called on
+  #   require "open-uri"
+  #   URI.open("http://example.com") { |f| f.read }
+  #
+  # If the first argument responds to the +open+ method, +open+ is called on
   # it with the rest of the arguments.
   #
   # If the first argument is a string that begins with <code>(protocol)://</code>, it is parsed by
-  # URI.parse.  If the parsed object responds to the 'open' method,
-  # 'open' is called on it with the rest of the arguments.
+  # URI.parse.  If the parsed object responds to the +open+ method,
+  # +open+ is called on it with the rest of the arguments.
   #
   # Otherwise, Kernel#open is called.
   #
   # OpenURI::OpenRead#open provides URI::HTTP#open, URI::HTTPS#open and
   # URI::FTP#open, Kernel#open.
   #
-  # We can accept URIs and strings that begin with http://, https:// and
-  # ftp://. In these cases, the opened file object is extended by OpenURI::Meta.
+  # We can accept URIs and strings that begin with <code>http://</code>, <code>https://</code> and
+  # <code>ftp://</code>. In these cases, the opened file object is extended by OpenURI::Meta.
   def self.open(name, *rest, &block)
     if name.respond_to?(:open)
       name.open(*rest, &block)