Add some more docs to doc/development/utilities.md1819-override-ce

2 files changed, 49 insertions, 1 deletions

diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md
index b4b5b47c099..f8cee89e650 100644
--- a/doc/development/ee_features.md
+++ b/doc/development/ee_features.md
@@ -87,7 +87,7 @@ still having access the class's implementation with `super`.
 
 There are a few gotchas with it:
 
-- you should always `extend ::Gitlab::Utils::Override` and use `override` to
+- you should always [`extend ::Gitlab::Utils::Override`] and use `override` to
   guard the "overrider" method to ensure that if the method gets renamed in
   CE, the EE override won't be silently forgotten.
 - when the "overrider" would add a line in the middle of the CE
@@ -192,6 +192,8 @@ module EE
 end
 ```
 
+[`extend ::Gitlab::Utils::Override`]: utilities.md#override
+
 #### Use self-descriptive wrapper methods
 
 When it's not possible/logical to modify the implementation of a
@@ -212,6 +214,7 @@ end
 In EE, the implementation `ee/app/models/ee/users.rb` would be:
 
 ```ruby
+override :full_private_access?
 def full_private_access?
   super || auditor?
 end
diff --git a/doc/development/utilities.md b/doc/development/utilities.md
index 951c3ef85ce..8f9aff1a35f 100644
--- a/doc/development/utilities.md
+++ b/doc/development/utilities.md
@@ -45,6 +45,51 @@ We developed a number of utilities to ease development.
     [:hello, "world", :this, :crushes, "an entire", "hash"]
     ```
 
+## [`Override`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/override.rb)
+
+* This utility could help us check if a particular method would override
+  another method or not. It has the same idea of Java's `@Override` annotation
+  or Scala's `override` keyword. However we only do this check when
+  `ENV['STATIC_VERIFICATION']` is set to avoid production runtime overhead.
+  This is useful to check:
+
+    * If we have typos in overriding methods.
+    * If we renamed the overridden methods, making original overriding methods
+      overrides nothing.
+
+    Here's a simple example:
+
+    ``` ruby
+    class Base
+      def execute
+      end
+    end
+
+    class Derived < Base
+      extend ::Gitlab::Utils::Override
+
+      override :execute # Override check happens here
+      def execute
+      end
+    end
+    ```
+
+    This also works on modules:
+
+    ``` ruby
+    module Extension
+      extend ::Gitlab::Utils::Override
+
+      override :execute # Modules do not check this immediately
+      def execute
+      end
+    end
+
+    class Derived < Base
+      prepend Extension # Override check happens here, not in the module
+    end
+    ```
+
 ## [`StrongMemoize`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/utils/strong_memoize.rb)
 
 * Memoize the value even if it is `nil` or `false`.