T-38 Docs for all public API, Uasge section in README.md

.gitignore

@@ -12,3 +12,6 @@
 
 # Hide `byebug` history
 .byebug_history
+
+# Ignore `Gemfile.lock`
+Gemfile.lock

.rubocop.yml

@@ -15,6 +15,9 @@ Metrics/AbcSize:
 Metrics/MethodLength:
   Max: 15
 
+Style/AsciiComments:
+  Enabled: No
+
 Style/Lambda:
   EnforcedStyle: literal
 

README.md

@@ -6,15 +6,21 @@
 
 ![alt text](https://raw.githubusercontent.com/marian13/basic_temperature/master/logo.png)
 
-Basic Temperature is a Ruby library which provides a simple value object to work with temperatures and allows to perform basic operations like conversion from Celsius to Kelvin, from Kelvin to Fahrenheit etc.
+`basic_temperature` is a Ruby library which provides a simple [value object](https://martinfowler.com/bliki/ValueObject.html) to work with temperatures and 
+allows to perform basic operations like conversion from Celsius to Kelvin, from Kelvin to Fahrenheit etc.
+
 
 ### Features
-- Provides a `BasicTemperature` class which encapsulates all information about a certain
-  temperature, such as its amount of degrees and its scale.
-- Provides APIs for exchanging temperatures from one scale to another (currently Celsius, Kelvin and Fahrenheit).
+- Provides a `BasicTemperature` class which encapsulates all information about a certain  temperature, such
+as its amount of degrees and its scale.
+- Provides APIs for exchanging temperatures from one scale to another (currently Celsius, Fahrenheit, Kelvin and
+Rankine).
+
 - Allows comparing temperatures between each other.
 - Supports basic math operations like addition and subtraction.
-- Tested against Ruby 2.3, 2.4, 2.5, 2.6 & 2.7. See [.travis-ci.yml](https://github.com/marian13/basic_temperature/blob/9b13cb9909b57c51bb5dc05a8989d07a314e67d6/.travis.yml) for the exact versions.
+- Tested against Ruby 2.3, 2.4, 2.5, 2.6 & 2.7. See
+[.travis-ci.yml](https://github.com/marian13/basic_temperature/blob/9b13cb9909b57c51bb5dc05a8989d07a314e67d6/.travis.yml)
+for the exact versions.
 
 ## Installation
 
@@ -42,49 +48,194 @@ Or install it yourself as:
 
 ## Usage
 
+### Creating Temperatures
+
+A new temperature can be created in multiple ways:
+
+- Using keyword arguments:
+
 ```ruby
-require 'basic_temperature'
+Temperature.new(degrees: 0, scale: :celsius)
+```
 
-temperature = BasicTemperature.new(degrees: 20, scale: :celsius)
-# Scale can be one of celsius, kelvin or fahrenheit.
+- Using positional arguments:
 
-temperature.to_celsius
-# => 20 Celsius
+```ruby
+Temperature.new(0, :celsius)
+```
 
-temperature.to_kelvin
-# => 293 Kelvin
+- Even more concise way using `Temperature.[]` (an alias of `Temperature.new`):
 
-temperature.to_fahrenheit
-# => 68 Fahrenheit
+```ruby
+Temperature[0, :celsius]
 ```
 
-You can try to utilize `BasicTemperature#to_scale` if you need to convert temperatures dynamically, for example:
+### Creating Temperatures from already existing temperature objects
+
+Sometimes it is useful to create a new temperature from already existing one.
+
+For such cases, there are `set_degrees` and `set_scale`.
+
+Since temperatures are [value objects](https://martinfowler.com/bliki/ValueObject.html), both methods returns
+new instances.
+
+Examples:
 
 ```ruby
-temperature.to_scale(scale)
+temperature = Temperature[0, :celsius]
+# => 0 °C
+
+new_temperature = temperature.set_degrees(15)
+# => 15 °C
+
+temperature = Temperature[0, :celsius]
+# => 0 °C
+
+new_temperature = temperature.set_scale(:kelvin)
+# => 0 K
 ```
 
-Temperatures can be compared between each other.
+### Conversions
+
+Temperatures can be converted to diffirent scales.
+
+Currently, the following scales are supported: `Celsius`, `Fahrenheit`, `Kelvin` and `Rankine`.
 
 ```ruby
-temperature = BasicTemperature.new(degress: 0, scale: :celsius)
+Temperature[20, :celsius].to_celsius
+# => 20 °C
 
-other = BasicTemperature.new(degress: 0, scale: :celsius)
+Temperature[20, :celsius].to_fahrenheit
+# => 68 °F
 
-temperature == other
+Temperature[20, :celsius].to_kelvin
+# => 293.15 K
+
+Temperature[20, :celsius].to_rankine
+# => 527.67 °R
+```
+
+If it is necessary to convert scale dynamically, `to_scale` method is available.
+
+```ruby
+Temperature[20, :celsius].to_scale(scale)
+```
+
+All conversion formulas are taken from
+[RapidTables](https://www.rapidtables.com/convert/temperature/index.html).
+
+Conversion precision: 2 accurate digits after the decimal dot.
+
+### Comparison
+
+Temperature implements idiomatic [<=> spaceship operator](https://ruby-doc.org/core/Comparable.html) and mixes in [Comparable](https://ruby-doc.org/core/Comparable.html) module.
+
+As a result, all methods from [Comparable](https://ruby-doc.org/core/Comparable.html) are available, e.g:
+
+```ruby
+Temperature[20, :celsius] < Temperature[25, :celsius]
+# => true
+
+Temperature[20, :celsius] <= Temperature[25, :celsius]
 # => true
+
+Temperature[20, :celsius] == Temperature[25, :celsius]
+# => false
+
+Temperature[20, :celsius] > Temperature[25, :celsius]
+# => false
+
+Temperature[20, :celsius] >= Temperature[25, :celsius]
+# => false
+
+Temperature[20, :celsius].between?(Temperature[15, :celsius], Temperature[25, :celsius])
+# => true
+
+# Starting from Ruby 2.4.6
+Temperature[20, :celsius].clamp?(Temperature[20, :celsius], Temperature[25, :celsius])
+# => 20 °C
 ```
 
-When temperatures have different scales - conversion to common scale is handled under the hood.
+Please note, if the second temperature has a different scale, the first temperature is automatically
+converted to that scale before comparison.
+
 ```ruby
-temperature = BasicTemperature.new(degress: 0, scale: :celsius)
+Temperature[20, :celsius] == Temperature[293.15, :kelvin]
+# => true
+```
+
+#### IMPORTANT !!!
+
+`degrees` are rounded to the nearest value with a precision of 2 decimal digits before comparison.
 
-other = BasicTemperature.new(degress: 273.15, scale: :kelvin)
+This means the following temperatures are considered as equal:
 
-temperature == other
+```ruby
+Temperature[20.020, :celsius] == Temperature[20.024, :celsius]
+# => true
+
+Temperature[20.025, :celsius] == Temperature[20.029, :celsius]
 # => true
 ```
 
+while these ones are treated as NOT equal:
+
+```ruby
+Temperature[20.024, :celsius] == Temperature[20.029, :celsius]
+# => false
+```
+
+### Math
+
+#### Addition/Subtraction.
+
+```ruby
+Temperature[20, :celsius] + Temperature[10, :celsius]
+# => 30 °C
+
+Temperature[20, :celsius] - Temperature[10, :celsius]
+# => 10 °C
+```
+
+If second temperature has a different scale, first temperature is automatically converted to that scale
+before `degrees` addition/subtraction.
+
+```ruby
+Temperature[283.15, :kelvin] + Temperature[10, :celsius]
+# => 10 °C
+```
+
+Returned temperature will have the same scale as the second temperature.
+
+It is possible to add/subtract numerics.
+
+```ruby
+Temperature[20, :celsius] + 10
+# => 30 °C
+
+Temperature[20, :celsius] - 10
+# => 10 °C
+```
+
+In such cases, returned temperature will have the same scale as the first temperature.
+
+Also [Ruby coersion mechanism](https://ruby-doc.org/core/Numeric.html#method-i-coerce) is supported.
+
+```ruby
+10 + Temperature[20, :celsius]
+# => 30 °C
+
+10 - Temperature[20, :celsius]
+# => -10 °C
+```
+
+#### Negation
+
+```ruby
+-Temperature[20, :celsius]
+# => -20 °C
+```
+
 ## Versioning
 Basic Temperature follows the [Semantic Versioning](https://semver.org/) standard.
 

basic_temperature.gemspec

@@ -35,8 +35,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'byebug', '~> 10.0'
   spec.add_development_dependency 'coveralls'
   spec.add_development_dependency 'rake', '~> 12.0'
+  spec.add_development_dependency 'rerun'
   spec.add_development_dependency 'reverse_coverage'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 0.80.0'
+  spec.add_development_dependency 'sdoc'
   spec.add_development_dependency 'simplecov'
 end