From e31e3d1514717ff2de3d76d13e7edc013485cbae Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Mon, 16 Sep 2024 15:15:17 -0400
Subject: [PATCH] Update docs

---
 docs/text.md | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/docs/text.md b/docs/text.md
index 153b783..3836953 100644
--- a/docs/text.md
+++ b/docs/text.md
@@ -276,7 +276,7 @@ functions that would normally be handled by a more extensive API:
 Text.has(pattern:Pattern)->Bool
 Text.find(pattern:Pattern, start=1, length=!&Int64?)->Int
 Text.find_all(pattern:Pattern)->[Text]
-Text.matches(pattern:Pattern)->Bool
+Text.matches(pattern:Pattern)->[Text]?
 Text.map(pattern:Pattern, fn:func(t:Text)->Text)->Text
 Text.replace(pattern:Pattern, replacement:Text, placeholder:Pattern=$//)->[Text]
 Text.replace_all(replacements:{Pattern:Text}, placeholder:Pattern=$//)->[Text]
@@ -840,11 +840,13 @@ The lowercase version of the text.
 ## `matches`
 
 **Description:**  
-Checks if the `Text` matches target pattern (see: [Patterns](#Patterns)).
+Checks if the `Text` matches target pattern (see: [Patterns](#Patterns)) and
+returns an array of the matching texts or a null value if the entire text
+doesn't match the pattern.
 
 **Usage:**  
 ```tomo
-matches(text: Text, pattern: Pattern) -> Bool
+matches(text: Text, pattern: Pattern) -> [Text]
 ```
 
 **Parameters:**
@@ -853,16 +855,16 @@ matches(text: Text, pattern: Pattern) -> Bool
 - `pattern`: The pattern to search for.
 
 **Returns:**  
-`yes` if the target pattern is found, `no` otherwise.
+An array of the matching text groups if the entire text matches the pattern, or
+a null value otherwise.
 
 **Example:**  
 ```tomo
->> "Hello":matches($/{id}/)
-= yes
->> "Hello":matches($/{upper}/)
-= no
->> "Hello":matches($/{lower}/)
-= no
+>> "hello world":matches($/{id}/)
+= ![Text]
+
+>> "hello world":matches($/{id} {id}/)
+= ["hello", "world"]?
 ```
 
 ---