From 1cd8f9823f6bf5067b52a0ddf8f219d823a7aded Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81lvaro=20Abella=20Bascar=C3=A1n?=
 <alvaroabascar@gmail.com>
Date: Wed, 9 Jan 2019 03:11:15 +0100
Subject: [PATCH] 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  | 4 ++--
 spacy/tokens/token.pyx | 5 +++--
 website/api/span.jade  | 4 ++--
 website/api/token.jade | 5 +++--
 4 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/spacy/tokens/span.pyx b/spacy/tokens/span.pyx
index 64e485412..0ddb509c2 100644
--- a/spacy/tokens/span.pyx
+++ b/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:
diff --git a/spacy/tokens/token.pyx b/spacy/tokens/token.pyx
index 381aa2aa8..38a34bbec 100644
--- a/spacy/tokens/token.pyx
+++ b/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:
diff --git a/website/api/span.jade b/website/api/span.jade
index e13fa29a5..a8d3a2b00 100644
--- a/website/api/span.jade
+++ b/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
diff --git a/website/api/token.jade b/website/api/token.jade
index 9a9a6dc1d..1303a37ec 100644
--- a/website/api/token.jade
+++ b/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