Improved documentation of new method.

2 files changed, 12 insertions, 7 deletions

diff --git a/CHANGELOG b/CHANGELOG
index 7b9b673..d213459 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -13,7 +13,7 @@ Python 2 was revision 70f546b1e689a70e2f103795efce6d261a3dadf7.
   This does mean one addition to the BeautifulSoup and Tag classes
   (the .css property itself), so this might be a breaking change if you
   happen to use Beautiful Soup to parse XML that includes a tag called
-  <css>. In particular, code like this will not work in 4.12.0:
+  <css>. In particular, code like this will stop working in 4.12.0:
 
     soup.css['id']
 
@@ -23,9 +23,9 @@ Python 2 was revision 70f546b1e689a70e2f103795efce6d261a3dadf7.
 
   The Soup Sieve methods supported through the .css property are
   select(), select_one(), iselect(), closest(), match(), filter(),
-  and escape(). The BeautifulSoup and Tag classes still support the
-  select() and select_one() methods; they have not been deprecated,
-  but they have been demoted to convenience methods.
+  escape(), and compile(). The BeautifulSoup and Tag classes still
+  support the select() and select_one() methods; they have not been
+  deprecated, but they have been demoted to convenience methods.
 
   [bug=2003677]
 
diff --git a/bs4/css.py b/bs4/css.py
index 3cf4df1..197bfaf 100644
--- a/bs4/css.py
+++ b/bs4/css.py
@@ -58,6 +58,9 @@ class CSS(object):
     def _ns(self, ns, select):
         """Normalize a dictionary of namespaces."""
         if not isinstance(select, self.api.SoupSieve) and ns is None:
+            # If the selector is a precompiled pattern, it already has
+            # a namespace context compiled in, which cannot be
+            # replaced.
             ns = self.tag._namespaces
         return ns
 
@@ -84,15 +87,17 @@ class CSS(object):
            parsing the document.
 
         :param flags: Flags to be passed into Soup Sieve's
-            soupsieve.select_one() method.
+            soupsieve.compile() method.
 
         :param kwargs: Keyword arguments to be passed into SoupSieve's
-           soupsieve.select_one() method.
+           soupsieve.compile() method.
 
         :return: A precompiled selector object.
         :rtype: soupsieve.SoupSieve
         """
-        return self.api.compile(select, self._ns(namespaces, select), flags, **kwargs)
+        return self.api.compile(
+            select, self._ns(namespaces, select), flags, **kwargs
+        )
 
     def select_one(self, select, namespaces=None, flags=0, **kwargs):
         """Perform a CSS selection operation on the current Tag and return the