Fixed `signup_domain_valid?` flow and added documentation.

app/models/user.rb

@@ -760,41 +760,31 @@ class User < ActiveRecord::Base
     Project.where(id: events)
   end
 
-  def match_domain(email_domains)
-    email_domains.any? do |domain|
-      escaped = Regexp.escape(domain).gsub('\*', '.*?')
-      regexp = Regexp.new "^#{escaped}$", Regexp::IGNORECASE
-      email_domain = Mail::Address.new(self.email).domain
-      email_domain =~ regexp
-    end
-  end
-
   def signup_domain_valid?
     valid = true
+    error = nil
 
     if current_application_settings.domain_blacklist_enabled?
       blocked_domains = current_application_settings.domain_blacklist
-      if match_domain(blocked_domains)
-        self.errors.add :email, 'is not from an allowed domain.'
+      if match_domain(blocked_domains, self.email)
+        error = 'is not from an allowed domain.'
         valid = false
       end
     end
 
     allowed_domains = current_application_settings.restricted_signup_domains
     unless allowed_domains.blank?
-      if match_domain(allowed_domains)
-        self.errors.clear
+      if match_domain(allowed_domains, self.email)
         valid = true
       else
-        self.errors.add :email,
-                        'is not whitelisted. ' +
-                        'Email domains valid for registration are: ' +
-                        allowed_domains.join(', ')
+        error = "is not whitelisted. Email domains valid for registration are: #{allowed_domains.join(', ')}"
         valid = false
       end
     end
 
-    return valid
+    self.errors.add(:email, error) unless valid
+
+    valid
   end
 
   def can_be_removed?
@@ -895,4 +885,15 @@ class User < ActiveRecord::Base
     self.can_create_group   = false
     self.projects_limit     = 0
   end
+
+  private
+
+  def match_domain(email_domains, email)
+    signup_domain = Mail::Address.new(email).domain
+    email_domains.any? do |domain|
+      escaped = Regexp.escape(domain).gsub('\*', '.*?')
+      regexp = Regexp.new "^#{escaped}$", Regexp::IGNORECASE
+      signup_domain =~ regexp
+    end
+  end
 end

doc/administration/access_restrictions.md

 # Access Restrictions
 
-> **Note:** This feature is only available on versions 8.10 and above.
+> **Note:** These features are only available on versions 8.10 and above.
 
 With GitLab's Access restrictions you can choose which Git access protocols you
 want your users to use to communicate with GitLab. This feature can be enabled
@@ -35,4 +35,22 @@ not selected.
 > **Note:** Please keep in mind that disabling an access protocol does not actually
   block access to the server itself. The ports used for the protocol, be it SSH or
   HTTP, will still be accessible. What GitLab does is restrict access on the
-  application level.
+  application level.
\ No newline at end of file
+
+## Blacklist email domains
+
+With this feature enabled, you can block email addresses of an specific domain
+from creating an account on your GitLab server. This is particularly useful to
+prevent spam. Disposable email addresses are usually used by malicious users to
+create dummy accounts and spam issues.
+
+This feature can be activated via the `Application Settings` in the Admin area,
+and you have the option of entering the list manually, or uploading a file with
+the list.
+
+The blacklist accepts wildcards, so you can use `*.test.com` to block every
+`test.com` subdomain, or `*.io` to block all domains ending in `.io`. Domains
+should be separated by a whitespace, semicolon, comma, or a new line.
+
+![Domain Blacklist](img/domain_blacklist.png)
+