From 981c34917f44d96b5c7fa3314bcf39c772d12a61 Mon Sep 17 00:00:00 2001
From: Leonard Richardson <leonardr@segfault.org>
Date: Wed, 1 Jan 2020 13:30:28 -0500
Subject: API CHANGE - Added PageElement.decomposed, a new property which lets
 you   check whether you've already called decompose() on a Tag or  
 NavigableString.

---
 doc/source/index.rst | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

(limited to 'doc/source')

diff --git a/doc/source/index.rst b/doc/source/index.rst
index baaf09c..3664612 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -97,7 +97,7 @@ data structure::
  #     Lacie
  #    </a>
  #    and
- #    <a class="sister" href="http://example.com/tillie" id="link2">
+ #    <a class="sister" href="http://example.com/tillie" id="link3">
  #     Tillie
  #    </a>
  #    ; and they lived at the bottom of a well.
@@ -2067,12 +2067,23 @@ destroys it and its contents`::
   markup = '<a href="http://example.com/">I linked to <i>example.com</i></a>'
   soup = BeautifulSoup(markup)
   a_tag = soup.a
+  i_tag = soup.i
 
-  soup.i.decompose()
-
+  i_tag.decompose()
   a_tag
   # <a href="http://example.com/">I linked to</a>
 
+The behavior of a decomposed ``Tag`` or ``NavigableString`` is not
+defined and you should not use it for anything. If you're not sure
+whether something has been decomposed, you can check its
+``.decomposed`` property (new in 4.9.0)::
+
+  i_tag.decomposed
+  # True
+
+  a_tag.decomposed
+  # False
+
 
 .. _replace_with():
 
-- 
cgit v1.2.3