Add Comprehensive YARD Documentation and Update README

README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/world_time_api.svg)](https://badge.fury.io/rb/world_time_api)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/world_time_api`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Ruby wrapper for the World Time API.
 
 ## Installation
 
@@ -26,14 +26,22 @@ gem install world_time_api
 
 ## Usage
 
+### List timezones
+
 ```ruby
-WorldTimeApi::Timezones.call # list timezones
+WorldTimeApi::Timezones.call
+```
+
+### Get time by timezone
 
-WorldTimeApi::Time.call(time_zone) # get datetime of the timezone
+```ruby
+WorldTimeApi::Time.call('Europe/London')
+```
 
-WorldTimeApi::ClientIp.call # get datetime by your client ip
+### Get time by IP address
 
-WorldTimeApi::ClientIp.call(ip_address) # get datatime by ip address
+```ruby
+WorldTimeApi::ClientIp.call('12.215.42.19')
 ```
 
 ## Development

lib/world_time_api.rb

@@ -6,23 +6,28 @@
 require_relative "world_time_api/response"
 require_relative "world_time_api/error"
 
-# The WorldTimeApi module contains methods for making requests to the World Time API.
+# A Ruby wrapper for the World Time API.
 module WorldTimeApi
-
   # Returns a list of all timezones supported by the World Time API.
   #
-  # @return [WorldTimeApi::Response] The API response.
+  # @return [Hash] A hash representing the response body, or an error hash if there was a problem with the request.
+  # @example
+  #   WorldTimeApi::Timezones.call
   Timezones = -> { Request::Call["/timezone"] }
 
   # Returns the current time for the specified timezone.
   #
   # @param timezone [String] The timezone ID.
-  # @return [WorldTimeApi::Response] The API response.
-  Time = -> (timezone) { Request::Call["/timezone/#{timezone}"] }
+  # @return [Hash] A hash representing the response body, or an error hash if there was a problem with the request.
+  # @example
+  #   WorldTimeApi::Time.call('Europe/London')
+  Time = ->(timezone) { Request::Call["/timezone/#{timezone}"] }
 
   # Returns the current time for the client's IP address, or for the specified IP address if provided.
   #
   # @param ip [String] (optional) The IP address to lookup.
-  # @return [WorldTimeApi::Response] The API response.
-  ClientIp = -> (ip = nil) { Request::Call["/ip#{ip ? "/#{ip}" : ''}"] }
+  # @return [Hash] A hash representing the response body, or an error hash if there was a problem with the request.
+  # @example
+  #   WorldTimeApi::ClientIp.call('127.0.0.1')
+  ClientIp = ->(ip = nil) { Request::Call["/ip#{ip ? "/#{ip}" : ''}"] }
 end

lib/world_time_api/error.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-# The WorldTimeApi module contains methods for making requests to the World Time API.
+# A Ruby wrapper for the World Time API.
 module WorldTimeApi
-
   # Creates an error object with the specified message.
   #
   # @param message [String] The error message.
   # @return [Hash] A hash with a single key `"error"` containing the error message.
-  Error = -> (message) { { error: message } }
+  # @example
+  #   WorldTimeApi::Error.call('Invalid timezone')
+  Error = ->(message) { { error: message } }
 end

lib/world_time_api/request.rb

@@ -4,10 +4,9 @@
 require_relative "error"
 require 'httparty'
 
-# The WorldTimeApi module contains methods for making requests to the World Time API.
+# A Ruby wrapper for the World Time API.
 module WorldTimeApi
-
-  # The Request module contains methods for making HTTP requests to the World Time API.
+  # A module for making HTTP requests to the World Time API.
   module Request
     include HTTParty
 
@@ -17,6 +16,8 @@ module Request
     #
     # @param url [String] The URL to make the request to.
     # @return [Hash] A hash representing the response body, or an error hash if there was a problem with the request.
+    # @example
+    #   WorldTimeApi::Request::Call.call('/timezone/Europe/London')
     Call = ->(url) {
       begin
         response = get(url)

lib/world_time_api/response.rb

@@ -2,12 +2,13 @@
 
 require 'json'
 
-# The WorldTimeApi module contains methods for making requests to the World Time API.
+# A Ruby wrapper for the World Time API.
 module WorldTimeApi
-
   # Converts the HTTParty response object into a hash.
   #
   # @param response [HTTParty::Response] The HTTParty response object to convert.
   # @return [Hash] A hash representation of the response body.
-  Response = -> (response) { JSON.parse(response.body) }
+  # @example
+  #   WorldTimeApi::Response.call(HTTParty.get('http://worldtimeapi.org/api/timezone/Europe/London'))
+  Response = ->(response) { JSON.parse(response.body) }
 end

lib/world_time_api/version.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-# The WorldTimeApi module contains methods for making requests to the World Time API.
+# A Ruby wrapper for the World Time API.
 module WorldTimeApi
-
   # The current version number of the WorldTimeApi gem.
   VERSION = "0.1.5"
 end