diff --git a/lib/uri/common.rb b/lib/uri/common.rb
index ec85bbc1e7..74bbdea0a4 100644
--- a/lib/uri/common.rb
+++ b/lib/uri/common.rb
@@ -114,6 +114,12 @@ module URI
     # +str+::
     #   Unescapes the string.
     #
+    # == Description
+    #
+    # This method is obsolete and should not be used. Instead, use
+    # CGI.unescape, URI.decode_www_form or URI.decode_www_form_component
+    # depending on your specific use case.
+    #
     # == Usage
     #
     #   require 'uri'