Added documentation; no need to create reference to search result

Dave Sims · Dave Sims · commit 03c7d90c40d2 · 2016-07-11T09:36:59.000-05:00
diff --git a/lib/github/ldap/forest_search.rb b/lib/github/ldap/forest_search.rb
@@ -7,26 +7,43 @@ class Ldap
     class ForestSearch
       include Instrumentation
 
+      # Build a new GitHub::Ldap::ForestSearch instance
+      #
+      # connection:     GitHub::Ldap object representing the main AD connection.
+      # naming_context: The Distinguished Name (DN) of this forest's Configuration
+      #                 Naming Context, e.g., "CN=Configuration,DC=ad,DC=ghe,DC=com"
+      #
+      # See: https://technet.microsoft.com/en-us/library/aa998375(v=exchg.65).aspx
+      #
       def initialize(connection, naming_context)
         @naming_context = naming_context
         @connection = connection
-        @forest = get_domain_forest
       end
 
+      # Search over all domain controllers in the ActiveDirectory forest.
+      #
+      # options: options hash passed in from GitHub::Ldap#search
+      # &block:  optional block passed in from GitHub::Ldap#search
+      #
+      # If no domain controllers are found in the forest, fall back on searching
+      # the main GitHub::Ldap object in @connection.
+      #
+      # If @forest is populated, iterate over each domain controller and perform
+      # the requested search, excluding domain controllers whose naming context
+      # is not in scope for the search base DN defined in options[:base].
+      #
       def search(options, &block)
-        instrument "forest_search.github_ldap" do |payload|
-          result =
-            if @forest.empty?
-              @connection.search(options, &block)
-            else
-              @forest.each_with_object([]) do |(rootdn, server), res|
-                if options[:base].end_with?(rootdn)
-                  rs = server.search(options, &block)
-                  res.concat Array(rs) unless rs == false
-                end
+        instrument "forest_search.github_ldap" do
+          if forest.empty?
+            @connection.search(options, &block)
+          else
+            forest.each_with_object([]) do |(ncname, connection), res|
+              if options[:base].end_with?(ncname)
+                rs = connection.search(options, &block)
+                res.concat Array(rs) unless rs == false
               end
             end
-          return result
+          end
         end
       end
 
