Correct docs of `Token.subtree` and `Span.subtree` (issue #3122) (#3124)

* solve inconsistency between docs and Span.subtree (issue #3122)

* solve inconsistency between docs and Token.subtree (issue #3122)

spacy/tokens/span.pyx

@@ -491,9 +491,9 @@ cdef class Span:
             return len(list(self.rights))
 
     property subtree:
-        """Tokens that descend from tokens in the span, but fall outside it.
+        """Tokens within the span and tokens which descend from them.
 
-        YIELDS (Token): A descendant of a token within the span.
+        YIELDS (Token): A token within the span, or a descendant from it.
         """
         def __get__(self):
             for word in self.lefts:

spacy/tokens/token.pyx

@@ -451,10 +451,11 @@ cdef class Token:
             yield from self.rights
 
     property subtree:
-        """A sequence of all the token's syntactic descendents.
+        """A sequence containing the token and all the token's syntactic
+        descendants.
 
         YIELDS (Token): A descendent token such that
-            `self.is_ancestor(descendent)`.
+            `self.is_ancestor(descendent) or token == self`.
         """
         def __get__(self):
             for word in self.lefts:

website/api/span.jade

@@ -489,7 +489,7 @@ p
     +tag property
     +tag-model("parse")
 
-p Tokens that descend from tokens in the span, but fall outside it.
+p Tokens within the span and tokens which descend from them.
 
 +aside-code("Example").
     doc = nlp(u'Give it back! He pleaded.')
@@ -500,7 +500,7 @@ p Tokens that descend from tokens in the span, but fall outside it.
     +row("foot")
         +cell yields
         +cell #[code Token]
-        +cell A descendant of a token within the span.
+        +cell A token within the span, or a descendant from it.
 
 +h(2, "has_vector") Span.has_vector
     +tag property

website/api/token.jade

@@ -1,3 +1,4 @@
+
 //- 💫 DOCS > API > TOKEN
 
 include ../_includes/_mixins
@@ -405,7 +406,7 @@ p
     +tag property
     +tag-model("parse")
 
-p A sequence of all the token's syntactic descendants.
+p A sequence containing the token and all the token's syntactic descendants.
 
 +aside-code("Example").
     doc = nlp(u'Give it back! He pleaded.')
@@ -416,7 +417,7 @@ p A sequence of all the token's syntactic descendants.
     +row("foot")
         +cell yields
         +cell #[code Token]
-        +cell A descendant token such that #[code self.is_ancestor(descendant)].
+        +cell A descendant token such that #[code self.is_ancestor(token) or token == self].
 
 +h(2, "is_sent_start") Token.is_sent_start
     +tag property