document `Flask.register_blueprint` arguments

closes #1809

flask/app.py

@@ -994,22 +994,41 @@ class Flask(_PackageBoundObject):
         return self.session_interface.make_null_session(self)
 
     @setupmethod
-    def register_blueprint(self, blueprint, **options):
+    def register_blueprint(
-        """Registers a blueprint on the application.
+        self, blueprint, **options
+    ):
+        """Register a :class:`~flask.Blueprint` on the application. Keyword
+        arguments passed to this method will override the defaults set on the
+        blueprint.
+
+        Calls the blueprint's :meth:`~flask.Blueprint.register` method after
+        recording the blueprint in the application's :attr:`blueprints`.
+
+        :param url_prefix: Blueprint routes will be prefixed with this.
+        :param subdomain: Blueprint routes will match on this subdomain.
+        :param url_defaults: Blueprint routes will use these default values for
+            view arguments.
+        :param options: Additional keyword arguments are passed to
+            :class:`~flask.blueprints.BlueprintSetupState`. They can be
+            accessed in :meth:`~flask.Blueprint.record` callbacks.
 
         .. versionadded:: 0.7
         """
         first_registration = False
+
         if blueprint.name in self.blueprints:
-            assert self.blueprints[blueprint.name] is blueprint, \
+            assert self.blueprints[blueprint.name] is blueprint, (
-                'A blueprint\'s name collision occurred between %r and ' \
+                'A name collision occurred between blueprints %r and %r. Both'
-                '%r.  Both share the same name "%s".  Blueprints that ' \
+                ' share the same name "%s". Blueprints that are created on the'
-                'are created on the fly need unique names.' % \
+                ' fly need unique names.' % (
-                (blueprint, self.blueprints[blueprint.name], blueprint.name)
+                    blueprint, self.blueprints[blueprint.name], blueprint.name
+                )
+            )
         else:
             self.blueprints[blueprint.name] = blueprint
             self._blueprint_order.append(blueprint)
             first_registration = True
+
         blueprint.register(self, options, first_registration)
 
     def iter_blueprints(self):

flask/blueprints.py

@@ -159,18 +159,25 @@ class Blueprint(_PackageBoundObject):
         return BlueprintSetupState(self, app, options, first_registration)
 
     def register(self, app, options, first_registration=False):
-        """Called by :meth:`Flask.register_blueprint` to register a blueprint
+        """Called by :meth:`Flask.register_blueprint` to register all views
-        on the application.  This can be overridden to customize the register
+        and callbacks registered on the blueprint with the application. Creates
-        behavior.  Keyword arguments from
+        a :class:`.BlueprintSetupState` and calls each :meth:`record` callback
-        :func:`~flask.Flask.register_blueprint` are directly forwarded to this
+        with it.
-        method in the `options` dictionary.
+
+        :param app: The application this blueprint is being registered with.
+        :param options: Keyword arguments forwarded from
+            :meth:`~Flask.register_blueprint`.
+        :param first_registration: Whether this is the first time this
+            blueprint has been registered on the application.
         """
         self._got_registered_once = True
         state = self.make_setup_state(app, options, first_registration)
+
         if self.has_static_folder:
-            state.add_url_rule(self.static_url_path + '/<path:filename>',
+            state.add_url_rule(
-                               view_func=self.send_static_file,
+                self.static_url_path + '/<path:filename>',
-                               endpoint='static')
+                view_func=self.send_static_file, endpoint='static'
+            )
 
         for deferred in self.deferred_functions:
             deferred(state)