More docstrings for blueprints.

flask/blueprints.py

@@ -16,25 +16,46 @@ from .helpers import _PackageBoundObject, _endpoint_from_view_func
 
 class BlueprintSetupState(object):
     """Temporary holder object for registering a blueprint with the
-    application.
+    application.  An instance of this class is created by the
+    :meth:`~flask.Blueprint.make_setup_state` method and later passed
+    to all register callback functions.
     """
 
     def __init__(self, blueprint, app, options, first_registration):
+        #: a reference to the current application
         self.app = app
+
+        #: a reference to the blurprint that created this setup state.
         self.blueprint = blueprint
+
+        #: a dictionary with all options that were passed to the
+        #: :meth:`~flask.Flask.register_blueprint` method.
         self.options = options
+
+        #: as blueprints can be registered multiple times with the
+        #: application and not everything wants to be registered
+        #: multiple times on it, this attribute can be used to figure
+        #: out if the blueprint was registered in the past already.
         self.first_registration = first_registration
 
         subdomain = self.options.get('subdomain')
         if subdomain is None:
             subdomain = self.blueprint.subdomain
+
+        #: The subdomain that the blueprint should be active for, `None`
+        #: otherwise.
         self.subdomain = subdomain
 
         url_prefix = self.options.get('url_prefix')
         if url_prefix is None:
             url_prefix = self.blueprint.url_prefix
+
+        #: The prefix that should be used for all URLs defined on the
+        #: blueprint.
         self.url_prefix = url_prefix
 
+        #: A dictionary with URL defaults that is added to each and every
+        #: URL that was defined with the blueprint.
         self.url_defaults = dict(self.blueprint.url_defaults)
         self.url_defaults.update(self.options.get('url_defaults', ()))
 
@@ -56,7 +77,11 @@ class BlueprintSetupState(object):
 
 
 class Blueprint(_PackageBoundObject):
-    """Represents a blueprint.
+    """Represents a blueprint.  A blueprint is an object that records
+    functions that will be called with the
+    :class:`~flask.blueprint.BlueprintSetupState` later to register functions
+    or other things on the main application.  See :ref:`blueprints` for more
+    information.
 
     .. versionadded:: 0.7
     """
@@ -104,6 +129,10 @@ class Blueprint(_PackageBoundObject):
         return self.record(update_wrapper(wrapper, func))
 
     def make_setup_state(self, app, options, first_registration=False):
+        """Creates an instance of :meth:`~flask.blueprints.BlueprintSetupState`
+        object that is later passed to the register callback functions.
+        Subclasses can override this to return a subclass of the setup state.
+        """
         return BlueprintSetupState(self, app, options, first_registration)
 
     def register(self, app, options, first_registration=False):
@@ -254,8 +283,6 @@ class Blueprint(_PackageBoundObject):
 
         Otherwise works as the :meth:`~flask.Flask.errorhandler` decorator
         of the :class:`~flask.Flask` object.
-
-        .. versionadded:: 0.7
         """
         def decorator(f):
             self.record_once(lambda s: s.app._register_error_handler(