Update README

Author: knu

README.md

@@ -1,8 +1,39 @@
 # Set
 
-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/set`. To experiment with that code, run `bin/console` for an interactive prompt.
+This library provides the Set class, which deals with a collection of
+unordered values with no duplicates.  It is a hybrid of Array's
+intuitive inter-operation facilities and Hash's fast lookup.
 
-TODO: Delete this and the text above, and describe your gem
+The method `to_set` is added to Enumerable for convenience.
+
+Set implements a collection of unordered values with no duplicates.
+This is a hybrid of Array's intuitive inter-operation facilities and
+Hash's fast lookup.
+
+Set is easy to use with Enumerable objects (implementing `each`).
+Most of the initializer methods and binary operators accept generic
+Enumerable objects besides sets and arrays.  An Enumerable object can
+be converted to Set using the `to_set` method.
+
+Set uses Hash as storage, so you must note the following points:
+
+* Equality of elements is determined according to Object#eql? and
+  Object#hash.  Use Set#compare_by_identity to make a set compare its
+  elements by their identity.
+
+* Set assumes that the identity of each element does not change while
+  it is stored.  Modifying an element of a set will render the set to
+  an unreliable state.
+
+* When a string is to be stored, a frozen copy of the string is stored
+  instead unless the original string is already frozen.
+
+### Comparison
+
+The comparison operators `<`, `>`, `<=`, and `>=` are implemented as
+shorthand for the {proper_,}{subset?,superset?} methods.  The `<=>`
+operator reflects this order, or return `nil` for sets that both have
+distinct elements (`{x, y}` vs. `{x, z}` for example).
 
 ## Installation
 
@@ -37,8 +68,6 @@ s2.subset?(s1)                        #=> true
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/set.