From d5c7fe29c863564d631f48a2b6e81241b5171aaf 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, moved from comments

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

(limited to 'doc/development/utilities.md')

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
+```
-- 
cgit v1.2.1