Merge pull request #46211 from hmbreaux/add-doc-routing-draw-method

Add API documentation for Routing#draw [ci-skip]

(cherry picked from commit 348e609)

Author: jonathanhefner

actionpack/lib/action_dispatch/routing/mapper.rb

@@ -1584,6 +1584,29 @@ def shallow?
           !parent_resource.singleton? && @scope[:shallow]
         end
 
+        # Loads another routes file with the given +name+ located inside the
+        # +config/routes+ directory. In that file, you can use the normal
+        # routing DSL, but <i>do not</i> surround it with a
+        # +Rails.application.routes.draw+ block.
+        #
+        #   # config/routes.rb
+        #   Rails.application.routes.draw do
+        #     draw :admin                 # Loads `config/routes/admin.rb`
+        #     draw "third_party/some_gem" # Loads `config/routes/third_party/some_gem.rb`
+        #   end
+        #
+        #   # config/routes/admin.rb
+        #   namespace :admin do
+        #     resources :accounts
+        #   end
+        #
+        #   # config/routes/third_party/some_gem.rb
+        #   mount SomeGem::Engine, at: "/some_gem"
+        #
+        # <b>CAUTION:</b> Use this feature with care. Having multiple routes
+        # files can negatively impact discoverability and readability. For most
+        # applications — even those with a few hundred routes — it's easier for
+        # developers to have a single routes file.
         def draw(name)
           path = @draw_paths.find do |_path|
             File.exist? "#{_path}/#{name}.rb"

guides/source/routing.md

@@ -1273,7 +1273,7 @@ video = Video.find_by(identifier: "Roman-Holiday")
 edit_video_path(video) # => "/videos/Roman-Holiday/edit"
 ```
 
-Breaking Up *Very* Large Route File into Multiple Small Ones:
+Breaking Up *Very* Large Route File into Multiple Small Ones
 -------------------------------------------------------
 
 If you work in a large application with thousands of routes, a single `config/routes.rb` file can become cumbersome and hard to read.