From 577203fa9e54a6fa33d8ae999edc8db26de2c11c Mon Sep 17 00:00:00 2001
From: Lin Jen-Shin <godfat@godfat.org>
Date: Thu, 21 Jun 2018 19:46:52 +0800
Subject: Add docs for RequestCache, copied from comments

---
 doc/development/utilities.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'doc/development')

diff --git a/doc/development/utilities.md b/doc/development/utilities.md
index 8f9aff1a35f..6426e844954 100644
--- a/doc/development/utilities.md
+++ b/doc/development/utilities.md
@@ -135,3 +135,45 @@ 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:
+
+``` 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.
+Here's another example using customized method level values:
+
+``` 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
+```
+
+So that we could have different strategies for different methods
-- 
cgit v1.2.1