Add docs for RequestCache, moved from comments

2 files changed, 42 insertions, 36 deletions

diff --git a/doc/development/utilities.md b/doc/development/utilities.md
index 8f9aff1a35f..0d074a3ef05 100644
--- a/doc/development/utilities.md
+++ b/doc/development/utilities.md
@@ -135,3 +135,44 @@ We developed a number of utilities to ease development.
 
     Find.new.clear_memoization(:result)
     ```
+
+## [`RequestCache`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/cache/request_cache.rb)
+
+This module provides a simple way to cache values in RequestStore,
+and the cache key would be based on the class name, method name,
+optionally customized instance level values, optionally customized
+method level values, and optional method arguments.
+
+A simple example that only uses the instance level customised values:
+
+``` ruby
+class UserAccess
+  extend Gitlab::Cache::RequestCache
+
+  request_cache_key do
+    [user&.id, project&.id]
+  end
+
+  request_cache def can_push_to_branch?(ref)
+    # ...
+  end
+end
+```
+
+This way, the result of `can_push_to_branch?` would be cached in
+`RequestStore.store` based on the cache key. If `RequestStore` is not
+currently active, then it would be stored in a hash saved in an
+instance variable, so the cache logic would be the same.
+
+We can also set different strategies for different methods:
+
+``` ruby
+class Commit
+  extend Gitlab::Cache::RequestCache
+
+  def author
+    User.find_by_any_email(author_email.downcase)
+  end
+  request_cache(:author) { author_email.downcase }
+end
+```
diff --git a/lib/gitlab/cache/request_cache.rb b/lib/gitlab/cache/request_cache.rb
index ecc85f847d4..671b8e7e1b1 100644
--- a/lib/gitlab/cache/request_cache.rb
+++ b/lib/gitlab/cache/request_cache.rb
@@ -1,41 +1,6 @@
 module Gitlab
   module Cache
-    # This module provides a simple way to cache values in RequestStore,
-    # and the cache key would be based on the class name, method name,
-    # optionally customized instance level values, optionally customized
-    # method level values, and optional method arguments.
-    #
-    # A simple example:
-    #
-    # class UserAccess
-    #   extend Gitlab::Cache::RequestCache
-    #
-    #   request_cache_key do
-    #     [user&.id, project&.id]
-    #   end
-    #
-    #   request_cache def can_push_to_branch?(ref)
-    #     # ...
-    #   end
-    # end
-    #
-    # This way, the result of `can_push_to_branch?` would be cached in
-    # `RequestStore.store` based on the cache key. If RequestStore is not
-    # currently active, then it would be stored in a hash saved in an
-    # instance variable, so the cache logic would be the same.
-    # Here's another example using customized method level values:
-    #
-    # class Commit
-    #   extend Gitlab::Cache::RequestCache
-    #
-    #   def author
-    #     User.find_by_any_email(author_email.downcase)
-    #   end
-    #   request_cache(:author) { author_email.downcase }
-    # end
-    #
-    # So that we could have different strategies for different methods
-    #
+    # See https://docs.gitlab.com/ee/development/utilities.html#requestcache
     module RequestCache
       def self.extended(klass)
         return if klass < self